doxygen: prevent GPL license block from being parsed as doxygen comment.
[blender.git] / source / blender / python / intern / bpy_props.c
1 /*
2  * $Id$
3  *
4  * ***** BEGIN GPL LICENSE BLOCK *****
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License
8  * as published by the Free Software Foundation; either version 2
9  * of the License, or (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software Foundation,
18  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19  *
20  * Contributor(s): Campbell Barton
21  *
22  * ***** END GPL LICENSE BLOCK *****
23  */
24
25 #include <Python.h>
26
27 #include "bpy_props.h"
28 #include "bpy_rna.h"
29 #include "bpy_util.h"
30
31 #include "BLI_utildefines.h"
32
33 #include "RNA_define.h" /* for defining our own rna */
34 #include "RNA_enum_types.h"
35
36 #include "MEM_guardedalloc.h"
37
38 #include "../generic/py_capi_utils.h"
39
40 static EnumPropertyItem property_flag_items[] = {
41         {PROP_HIDDEN, "HIDDEN", 0, "Hidden", ""},
42         {PROP_ANIMATABLE, "ANIMATABLE", 0, "Animateable", ""},
43         {0, NULL, 0, NULL, NULL}};
44
45 static EnumPropertyItem property_flag_enum_items[] = {
46         {PROP_HIDDEN, "HIDDEN", 0, "Hidden", ""},
47         {PROP_ANIMATABLE, "ANIMATABLE", 0, "Animateable", ""},
48         {PROP_ENUM_FLAG, "ENUM_FLAG", 0, "Enum Flag", ""},
49         {0, NULL, 0, NULL, NULL}};
50
51 /* subtypes */
52 static EnumPropertyItem property_subtype_string_items[] = {
53         {PROP_FILEPATH, "FILE_PATH", 0, "File Path", ""},
54         {PROP_DIRPATH, "DIR_PATH", 0, "Directory Path", ""},
55         {PROP_FILENAME, "FILENAME", 0, "Filename", ""},
56
57         {PROP_NONE, "NONE", 0, "None", ""},
58         {0, NULL, 0, NULL, NULL}};
59
60 static EnumPropertyItem property_subtype_number_items[] = {
61         {PROP_UNSIGNED, "UNSIGNED", 0, "Unsigned", ""},
62         {PROP_PERCENTAGE, "PERCENTAGE", 0, "Percentage", ""},
63         {PROP_FACTOR, "FACTOR", 0, "Factor", ""},
64         {PROP_ANGLE, "ANGLE", 0, "Angle", ""},
65         {PROP_TIME, "TIME", 0, "Time", ""},
66         {PROP_DISTANCE, "DISTANCE", 0, "Distance", ""},
67
68         {PROP_NONE, "NONE", 0, "None", ""},
69         {0, NULL, 0, NULL, NULL}};
70
71 static EnumPropertyItem property_subtype_array_items[] = {
72         {PROP_COLOR, "COLOR", 0, "Color", ""},
73         {PROP_TRANSLATION, "TRANSLATION", 0, "Translation", ""},
74         {PROP_DIRECTION, "DIRECTION", 0, "Direction", ""},
75         {PROP_VELOCITY, "VELOCITY", 0, "Velocity", ""},
76         {PROP_ACCELERATION, "ACCELERATION", 0, "Acceleration", ""},
77         {PROP_MATRIX, "MATRIX", 0, "Matrix", ""},
78         {PROP_EULER, "EULER", 0, "Euler", ""},
79         {PROP_QUATERNION, "QUATERNION", 0, "Quaternion", ""},
80         {PROP_AXISANGLE, "AXISANGLE", 0, "Axis Angle", ""},
81         {PROP_XYZ, "XYZ", 0, "XYZ", ""},
82         {PROP_COLOR_GAMMA, "COLOR_GAMMA", 0, "Color Gamma", ""},
83         {PROP_LAYER, "LAYER", 0, "Layer", ""},
84
85         {PROP_NONE, "NONE", 0, "None", ""},
86         {0, NULL, 0, NULL, NULL}};
87
88 /* PyObject's */
89 static PyObject *pymeth_BoolProperty = NULL;
90 static PyObject *pymeth_BoolVectorProperty = NULL;
91 static PyObject *pymeth_IntProperty = NULL;
92 static PyObject *pymeth_IntVectorProperty = NULL;
93 static PyObject *pymeth_FloatProperty = NULL;
94 static PyObject *pymeth_FloatVectorProperty = NULL;
95 static PyObject *pymeth_StringProperty = NULL;
96 static PyObject *pymeth_EnumProperty = NULL;
97 static PyObject *pymeth_PointerProperty = NULL;
98 static PyObject *pymeth_CollectionProperty = NULL;
99 static PyObject *pymeth_RemoveProperty = NULL;
100
101
102 /* operators and classes use this so it can store the args given but defer
103  * running it until the operator runs where these values are used to setup
104  * the default args for that operator instance */
105 static PyObject *bpy_prop_deferred_return(PyObject *func, PyObject *kw)
106 {
107         PyObject *ret = PyTuple_New(2);
108         PyTuple_SET_ITEM(ret, 0, func);
109         Py_INCREF(func);
110
111         if(kw==NULL)
112                 kw= PyDict_New();
113         else
114                 Py_INCREF(kw);
115
116         PyTuple_SET_ITEM(ret, 1, kw);
117
118         return ret;
119 }
120
121 /* this define runs at the start of each function and deals with 
122  * returning a deferred property (to be registed later) */
123 #define BPY_PROPDEF_HEAD(_func) \
124         if (PyTuple_GET_SIZE(args) == 1) { \
125                 PyObject *ret; \
126                 self= PyTuple_GET_ITEM(args, 0); \
127                 args= PyTuple_New(0); \
128                 ret= BPy_##_func(self, args, kw); \
129                 Py_DECREF(args); \
130                 return ret; \
131         } \
132         else if (PyTuple_GET_SIZE(args) > 1) { \
133                  PyErr_SetString(PyExc_ValueError, "all args must be keywords"); \
134                 return NULL; \
135         } \
136         srna= srna_from_self(self, #_func"(...):"); \
137         if(srna==NULL) { \
138                 if(PyErr_Occurred()) \
139                         return NULL; \
140                 return bpy_prop_deferred_return((void *)pymeth_##_func, kw); \
141         } \
142
143 /* terse macros for error checks shared between all funcs cant use function
144  * calls because of static strins passed to pyrna_set_to_enum_bitfield */
145 #define BPY_PROPDEF_CHECK(_func, _property_flag_items) \
146         if(id_len >= MAX_IDPROP_NAME) { \
147                 PyErr_Format(PyExc_TypeError, #_func"(): '%.200s' too long, max length is %d", id, MAX_IDPROP_NAME-1); \
148                 return NULL; \
149         } \
150         if(RNA_def_property_free_identifier(srna, id) == -1) { \
151                 PyErr_Format(PyExc_TypeError, #_func"(): '%s' is defined as a non-dynamic type", id); \
152                 return NULL; \
153         } \
154         if(pyopts && pyrna_set_to_enum_bitfield(_property_flag_items, pyopts, &opts, #_func"(options={...}):")) \
155                 return NULL; \
156
157 #define BPY_PROPDEF_SUBTYPE_CHECK(_func, _property_flag_items, _subtype) \
158         BPY_PROPDEF_CHECK(_func, _property_flag_items) \
159         if(pysubtype && RNA_enum_value_from_id(_subtype, pysubtype, &subtype)==0) { \
160                 PyErr_Format(PyExc_TypeError, #_func"(subtype='%s'): invalid subtype", pysubtype); \
161                 return NULL; \
162         } \
163
164
165 #define BPY_PROPDEF_NAME_DOC \
166 "   :arg name: Name used in the user interface.\n" \
167 "   :type name: string\n" \
168
169
170 #define BPY_PROPDEF_DESC_DOC \
171 "   :arg description: Text used for the tooltip and api documentation.\n" \
172 "   :type description: string\n" \
173
174
175 #if 0
176 static int bpy_struct_id_used(StructRNA *srna, char *identifier)
177 {
178         PointerRNA ptr;
179         RNA_pointer_create(NULL, srna, NULL, &ptr);
180         return (RNA_struct_find_property(&ptr, identifier) != NULL);
181 }
182 #endif
183
184
185 /* Function that sets RNA, NOTE - self is NULL when called from python, but being abused from C so we can pass the srna allong
186  * This isnt incorrect since its a python object - but be careful */
187 static char BPy_BoolProperty_doc[] =
188 ".. function:: BoolProperty(name=\"\", description=\"\", default=False, options={'ANIMATABLE'}, subtype='NONE')\n"
189 "\n"
190 "   Returns a new boolean property definition.\n"
191 "\n"
192 BPY_PROPDEF_NAME_DOC
193 BPY_PROPDEF_DESC_DOC
194 "   :arg options: Enumerator in ['HIDDEN', 'ANIMATABLE'].\n"
195 "   :type options: set\n"
196 "   :arg subtype: Enumerator in ['UNSIGNED', 'PERCENTAGE', 'FACTOR', 'ANGLE', 'TIME', 'DISTANCE', 'NONE'].\n"
197 "   :type subtype: string\n"
198 ;
199 static PyObject *BPy_BoolProperty(PyObject *self, PyObject *args, PyObject *kw)
200 {
201         StructRNA *srna;
202
203         BPY_PROPDEF_HEAD(BoolProperty)
204
205         if(srna) {
206                 static const char *kwlist[] = {"attr", "name", "description", "default", "options", "subtype", NULL};
207                 const char *id=NULL, *name="", *description="";
208                 int id_len;
209                 int def=0;
210                 PropertyRNA *prop;
211                 PyObject *pyopts= NULL;
212                 int opts=0;
213                 char *pysubtype= NULL;
214                 int subtype= PROP_NONE;
215
216                 if (!PyArg_ParseTupleAndKeywords(args, kw, "s#|ssiO!s:BoolProperty", (char **)kwlist, &id, &id_len, &name, &description, &def, &PySet_Type, &pyopts, &pysubtype))
217                         return NULL;
218
219                 BPY_PROPDEF_SUBTYPE_CHECK(BoolProperty, property_flag_items, property_subtype_number_items)
220
221                 prop= RNA_def_property(srna, id, PROP_BOOLEAN, subtype);
222                 RNA_def_property_boolean_default(prop, def);
223                 RNA_def_property_ui_text(prop, name, description);
224
225                 if(pyopts) {
226                         if(opts & PROP_HIDDEN) RNA_def_property_flag(prop, PROP_HIDDEN);
227                         if((opts & PROP_ANIMATABLE)==0) RNA_def_property_clear_flag(prop, PROP_ANIMATABLE);
228                 }
229                 RNA_def_property_duplicate_pointers(srna, prop);
230         }
231
232         Py_RETURN_NONE;
233 }
234
235 static char BPy_BoolVectorProperty_doc[] =
236 ".. function:: BoolVectorProperty(name=\"\", description=\"\", default=(False, False, False), options={'ANIMATABLE'}, subtype='NONE', size=3)\n"
237 "\n"
238 "   Returns a new vector boolean property definition.\n"
239 "\n"
240 BPY_PROPDEF_NAME_DOC
241 BPY_PROPDEF_DESC_DOC
242 "   :arg default: sequence of booleans the length of *size*.\n"
243 "   :type default: sequence\n"
244 "   :arg options: Enumerator in ['HIDDEN', 'ANIMATABLE'].\n"
245 "   :type options: set\n"
246 "   :arg subtype: Enumerator in ['COLOR', 'TRANSLATION', 'DIRECTION', 'VELOCITY', 'ACCELERATION', 'MATRIX', 'EULER', 'QUATERNION', 'AXISANGLE', 'XYZ', 'COLOR_GAMMA', 'LAYER', 'NONE'].\n"
247 "   :type subtype: string\n"
248 "   :arg size: Vector dimensions in [1,  and " STRINGIFY(PYRNA_STACK_ARRAY) "].\n"
249 "   :type size: int\n"
250 ;
251 static PyObject *BPy_BoolVectorProperty(PyObject *self, PyObject *args, PyObject *kw)
252 {
253         StructRNA *srna;
254
255         BPY_PROPDEF_HEAD(BoolVectorProperty)
256
257         if(srna) {
258                 static const char *kwlist[] = {"attr", "name", "description", "default", "options", "subtype", "size", NULL};
259                 const char *id=NULL, *name="", *description="";
260                 int id_len;
261                 int def[PYRNA_STACK_ARRAY]={0};
262                 int size=3;
263                 PropertyRNA *prop;
264                 PyObject *pydef= NULL;
265                 PyObject *pyopts= NULL;
266                 int opts=0;
267                 char *pysubtype= NULL;
268                 int subtype= PROP_NONE;
269
270                 if (!PyArg_ParseTupleAndKeywords(args, kw, "s#|ssOO!si:BoolVectorProperty", (char **)kwlist, &id, &id_len, &name, &description, &pydef, &PySet_Type, &pyopts, &pysubtype, &size))
271                         return NULL;
272
273                 BPY_PROPDEF_SUBTYPE_CHECK(BoolVectorProperty, property_flag_items, property_subtype_array_items)
274
275                 if(size < 1 || size > PYRNA_STACK_ARRAY) {
276                         PyErr_Format(PyExc_TypeError, "BoolVectorProperty(size=%d): size must be between 0 and " STRINGIFY(PYRNA_STACK_ARRAY), size);
277                         return NULL;
278                 }
279
280                 if(pydef && PyC_AsArray(def, pydef, size, &PyBool_Type, "BoolVectorProperty(default=sequence)") < 0)
281                         return NULL;
282
283                 // prop= RNA_def_boolean_array(srna, id, size, pydef ? def:NULL, name, description);
284                 prop= RNA_def_property(srna, id, PROP_BOOLEAN, subtype);
285                 RNA_def_property_array(prop, size);
286                 if(pydef) RNA_def_property_boolean_array_default(prop, def);
287                 RNA_def_property_ui_text(prop, name, description);
288
289                 if(pyopts) {
290                         if(opts & PROP_HIDDEN) RNA_def_property_flag(prop, PROP_HIDDEN);
291                         if((opts & PROP_ANIMATABLE)==0) RNA_def_property_clear_flag(prop, PROP_ANIMATABLE);
292                 }
293                 RNA_def_property_duplicate_pointers(srna, prop);
294         }
295         
296         Py_RETURN_NONE;
297 }
298
299 static char BPy_IntProperty_doc[] =
300 ".. function:: IntProperty(name=\"\", description=\"\", default=0, min=-sys.maxint, max=sys.maxint, soft_min=-sys.maxint, soft_max=sys.maxint, step=1, options={'ANIMATABLE'}, subtype='NONE')\n"
301 "\n"
302 "   Returns a new int property definition.\n"
303 "\n"
304 BPY_PROPDEF_NAME_DOC
305 BPY_PROPDEF_DESC_DOC
306 "   :arg options: Enumerator in ['HIDDEN', 'ANIMATABLE'].\n"
307 "   :type options: set\n"
308 "   :arg subtype: Enumerator in ['UNSIGNED', 'PERCENTAGE', 'FACTOR', 'ANGLE', 'TIME', 'DISTANCE', 'NONE'].\n"
309 "   :type subtype: string\n"
310 ;
311 static PyObject *BPy_IntProperty(PyObject *self, PyObject *args, PyObject *kw)
312 {
313         StructRNA *srna;
314
315         BPY_PROPDEF_HEAD(IntProperty)
316
317         if(srna) {
318                 static const char *kwlist[] = {"attr", "name", "description", "default", "min", "max", "soft_min", "soft_max", "step", "options", "subtype", NULL};
319                 const char *id=NULL, *name="", *description="";
320                 int id_len;
321                 int min=INT_MIN, max=INT_MAX, soft_min=INT_MIN, soft_max=INT_MAX, step=1, def=0;
322                 PropertyRNA *prop;
323                 PyObject *pyopts= NULL;
324                 int opts=0;
325                 char *pysubtype= NULL;
326                 int subtype= PROP_NONE;
327
328                 if (!PyArg_ParseTupleAndKeywords(args, kw, "s#|ssiiiiiiO!s:IntProperty", (char **)kwlist, &id, &id_len, &name, &description, &def, &min, &max, &soft_min, &soft_max, &step, &PySet_Type, &pyopts, &pysubtype))
329                         return NULL;
330
331                 BPY_PROPDEF_SUBTYPE_CHECK(IntProperty, property_flag_items, property_subtype_number_items)
332
333                 prop= RNA_def_property(srna, id, PROP_INT, subtype);
334                 RNA_def_property_int_default(prop, def);
335                 RNA_def_property_range(prop, min, max);
336                 RNA_def_property_ui_text(prop, name, description);
337                 RNA_def_property_ui_range(prop, MAX2(soft_min, min), MIN2(soft_max, max), step, 3);
338
339                 if(pyopts) {
340                         if(opts & PROP_HIDDEN) RNA_def_property_flag(prop, PROP_HIDDEN);
341                         if((opts & PROP_ANIMATABLE)==0) RNA_def_property_clear_flag(prop, PROP_ANIMATABLE);
342                 }
343                 RNA_def_property_duplicate_pointers(srna, prop);
344         }
345         Py_RETURN_NONE;
346 }
347
348 static char BPy_IntVectorProperty_doc[] =
349 ".. function:: IntVectorProperty(name=\"\", description=\"\", default=(0, 0, 0), min=-sys.maxint, max=sys.maxint, soft_min=-sys.maxint, soft_max=sys.maxint, options={'ANIMATABLE'}, subtype='NONE', size=3)\n"
350 "\n"
351 "   Returns a new vector int property definition.\n"
352 "\n"
353 BPY_PROPDEF_NAME_DOC
354 BPY_PROPDEF_DESC_DOC
355 "   :arg default: sequence of ints the length of *size*.\n"
356 "   :type default: sequence\n"
357 "   :arg options: Enumerator in ['HIDDEN', 'ANIMATABLE'].\n"
358 "   :type options: set\n"
359 "   :arg subtype: Enumerator in ['COLOR', 'TRANSLATION', 'DIRECTION', 'VELOCITY', 'ACCELERATION', 'MATRIX', 'EULER', 'QUATERNION', 'AXISANGLE', 'XYZ', 'COLOR_GAMMA', 'LAYER', 'NONE'].\n"
360 "   :type subtype: string\n"
361 "   :arg size: Vector dimensions in [1,  and " STRINGIFY(PYRNA_STACK_ARRAY) "].\n"
362 "   :type size: int\n"
363 ;
364 static PyObject *BPy_IntVectorProperty(PyObject *self, PyObject *args, PyObject *kw)
365 {
366         StructRNA *srna;
367
368         BPY_PROPDEF_HEAD(IntVectorProperty)
369
370         if(srna) {
371                 static const char *kwlist[] = {"attr", "name", "description", "default", "min", "max", "soft_min", "soft_max", "step", "options", "subtype", "size", NULL};
372                 const char *id=NULL, *name="", *description="";
373                 int id_len;
374                 int min=INT_MIN, max=INT_MAX, soft_min=INT_MIN, soft_max=INT_MAX, step=1, def[PYRNA_STACK_ARRAY]={0};
375                 int size=3;
376                 PropertyRNA *prop;
377                 PyObject *pydef= NULL;
378                 PyObject *pyopts= NULL;
379                 int opts=0;
380                 char *pysubtype= NULL;
381                 int subtype= PROP_NONE;
382
383                 if (!PyArg_ParseTupleAndKeywords(args, kw, "s#|ssOiiiiiO!si:IntVectorProperty", (char **)kwlist, &id, &id_len, &name, &description, &pydef, &min, &max, &soft_min, &soft_max, &step, &PySet_Type, &pyopts, &pysubtype, &size))
384                         return NULL;
385
386                 BPY_PROPDEF_SUBTYPE_CHECK(IntVectorProperty, property_flag_items, property_subtype_array_items)
387
388                 if(size < 1 || size > PYRNA_STACK_ARRAY) {
389                         PyErr_Format(PyExc_TypeError, "IntVectorProperty(size=%d): size must be between 0 and " STRINGIFY(PYRNA_STACK_ARRAY), size);
390                         return NULL;
391                 }
392
393                 if(pydef && PyC_AsArray(def, pydef, size, &PyLong_Type, "IntVectorProperty(default=sequence)") < 0)
394                         return NULL;
395
396                 prop= RNA_def_property(srna, id, PROP_INT, subtype);
397                 RNA_def_property_array(prop, size);
398                 if(pydef) RNA_def_property_int_array_default(prop, def);
399                 RNA_def_property_range(prop, min, max);
400                 RNA_def_property_ui_text(prop, name, description);
401                 RNA_def_property_ui_range(prop, MAX2(soft_min, min), MIN2(soft_max, max), step, 3);
402
403                 if(pyopts) {
404                         if(opts & PROP_HIDDEN) RNA_def_property_flag(prop, PROP_HIDDEN);
405                         if((opts & PROP_ANIMATABLE)==0) RNA_def_property_clear_flag(prop, PROP_ANIMATABLE);
406                 }
407                 RNA_def_property_duplicate_pointers(srna, prop);
408         }
409         Py_RETURN_NONE;
410 }
411
412
413 static char BPy_FloatProperty_doc[] =
414 ".. function:: FloatProperty(name=\"\", description=\"\", default=0.0, min=sys.float_info.min, max=sys.float_info.max, soft_min=sys.float_info.min, soft_max=sys.float_info.max, step=3, precision=2, options={'ANIMATABLE'}, subtype='NONE', unit='NONE')\n"
415 "\n"
416 "   Returns a new float property definition.\n"
417 "\n"
418 BPY_PROPDEF_NAME_DOC
419 BPY_PROPDEF_DESC_DOC
420 "   :arg options: Enumerator in ['HIDDEN', 'ANIMATABLE'].\n"
421 "   :type options: set\n"
422 "   :arg subtype: Enumerator in ['UNSIGNED', 'PERCENTAGE', 'FACTOR', 'ANGLE', 'TIME', 'DISTANCE', 'NONE'].\n"
423 "   :type subtype: string\n"
424 "   :arg unit: Enumerator in ['NONE', 'LENGTH', 'AREA', 'VOLUME', 'ROTATION', 'TIME', 'VELOCITY', 'ACCELERATION'].\n"
425 "   :type unit: string\n"
426 ;
427 static PyObject *BPy_FloatProperty(PyObject *self, PyObject *args, PyObject *kw)
428 {
429         StructRNA *srna;
430
431         BPY_PROPDEF_HEAD(FloatProperty)
432
433         if(srna) {
434                 static const char *kwlist[] = {"attr", "name", "description", "default", "min", "max", "soft_min", "soft_max", "step", "precision", "options", "subtype", "unit", NULL};
435                 const char *id=NULL, *name="", *description="";
436                 int id_len;
437                 float min=-FLT_MAX, max=FLT_MAX, soft_min=-FLT_MAX, soft_max=FLT_MAX, step=3, def=0.0f;
438                 int precision= 2;
439                 PropertyRNA *prop;
440                 PyObject *pyopts= NULL;
441                 int opts=0;
442                 char *pysubtype= NULL;
443                 int subtype= PROP_NONE;
444                 char *pyunit= NULL;
445                 int unit= PROP_UNIT_NONE;
446
447                 if (!PyArg_ParseTupleAndKeywords(args, kw, "s#|ssffffffiO!ss:FloatProperty", (char **)kwlist, &id, &id_len, &name, &description, &def, &min, &max, &soft_min, &soft_max, &step, &precision, &PySet_Type, &pyopts, &pysubtype, &pyunit))
448                         return NULL;
449
450                 BPY_PROPDEF_SUBTYPE_CHECK(FloatProperty, property_flag_items, property_subtype_number_items)
451
452                 if(pyunit && RNA_enum_value_from_id(property_unit_items, pyunit, &unit)==0) {
453                         PyErr_Format(PyExc_TypeError, "FloatProperty(unit='%s'): invalid unit");
454                         return NULL;
455                 }
456
457                 prop= RNA_def_property(srna, id, PROP_FLOAT, subtype | unit);
458                 RNA_def_property_float_default(prop, def);
459                 RNA_def_property_range(prop, min, max);
460                 RNA_def_property_ui_text(prop, name, description);
461                 RNA_def_property_ui_range(prop, MAX2(soft_min, min), MIN2(soft_max, max), step, precision);
462
463                 if(pyopts) {
464                         if(opts & PROP_HIDDEN) RNA_def_property_flag(prop, PROP_HIDDEN);
465                         if((opts & PROP_ANIMATABLE)==0) RNA_def_property_clear_flag(prop, PROP_ANIMATABLE);
466                 }
467                 RNA_def_property_duplicate_pointers(srna, prop);
468         }
469         Py_RETURN_NONE;
470 }
471
472 static char BPy_FloatVectorProperty_doc[] =
473 ".. function:: FloatVectorProperty(name=\"\", description=\"\", default=(0.0, 0.0, 0.0), min=sys.float_info.min, max=sys.float_info.max, soft_min=sys.float_info.min, soft_max=sys.float_info.max, step=3, precision=2, options={'ANIMATABLE'}, subtype='NONE', size=3)\n"
474 "\n"
475 "   Returns a new vector float property definition.\n"
476 "\n"
477 BPY_PROPDEF_NAME_DOC
478 BPY_PROPDEF_DESC_DOC
479 "   :arg default: sequence of floats the length of *size*.\n"
480 "   :type default: sequence\n"
481 "   :arg options: Enumerator in ['HIDDEN', 'ANIMATABLE'].\n"
482 "   :type options: set\n"
483 "   :arg subtype: Enumerator in ['COLOR', 'TRANSLATION', 'DIRECTION', 'VELOCITY', 'ACCELERATION', 'MATRIX', 'EULER', 'QUATERNION', 'AXISANGLE', 'XYZ', 'COLOR_GAMMA', 'LAYER', 'NONE'].\n"
484 "   :type subtype: string\n"
485 "   :arg size: Vector dimensions in [1,  and " STRINGIFY(PYRNA_STACK_ARRAY) "].\n"
486 "   :type size: int\n"
487 ;
488 static PyObject *BPy_FloatVectorProperty(PyObject *self, PyObject *args, PyObject *kw)
489 {
490         StructRNA *srna;
491
492         BPY_PROPDEF_HEAD(FloatVectorProperty)
493
494         if(srna) {
495                 static const char *kwlist[] = {"attr", "name", "description", "default", "min", "max", "soft_min", "soft_max", "step", "precision", "options", "subtype", "size", NULL};
496                 const char *id=NULL, *name="", *description="";
497                 int id_len;
498                 float min=-FLT_MAX, max=FLT_MAX, soft_min=-FLT_MAX, soft_max=FLT_MAX, step=3, def[PYRNA_STACK_ARRAY]={0.0f};
499                 int precision= 2, size=3;
500                 PropertyRNA *prop;
501                 PyObject *pydef= NULL;
502                 PyObject *pyopts= NULL;
503                 int opts=0;
504                 char *pysubtype= NULL;
505                 int subtype= PROP_NONE;
506
507                 if (!PyArg_ParseTupleAndKeywords(args, kw, "s#|ssOfffffiO!si:FloatVectorProperty", (char **)kwlist, &id, &id_len, &name, &description, &pydef, &min, &max, &soft_min, &soft_max, &step, &precision, &PySet_Type, &pyopts, &pysubtype, &size))
508                         return NULL;
509
510                 BPY_PROPDEF_SUBTYPE_CHECK(FloatVectorProperty, property_flag_items, property_subtype_array_items)
511
512                 if(size < 1 || size > PYRNA_STACK_ARRAY) {
513                         PyErr_Format(PyExc_TypeError, "FloatVectorProperty(size=%d): size must be between 0 and " STRINGIFY(PYRNA_STACK_ARRAY), size);
514                         return NULL;
515                 }
516
517                 if(pydef && PyC_AsArray(def, pydef, size, &PyFloat_Type, "FloatVectorProperty(default=sequence)") < 0)
518                         return NULL;
519
520                 prop= RNA_def_property(srna, id, PROP_FLOAT, subtype);
521                 RNA_def_property_array(prop, size);
522                 if(pydef) RNA_def_property_float_array_default(prop, def);
523                 RNA_def_property_range(prop, min, max);
524                 RNA_def_property_ui_text(prop, name, description);
525                 RNA_def_property_ui_range(prop, MAX2(soft_min, min), MIN2(soft_max, max), step, precision);
526
527                 if(pyopts) {
528                         if(opts & PROP_HIDDEN) RNA_def_property_flag(prop, PROP_HIDDEN);
529                         if((opts & PROP_ANIMATABLE)==0) RNA_def_property_clear_flag(prop, PROP_ANIMATABLE);
530                 }
531                 RNA_def_property_duplicate_pointers(srna, prop);
532         }
533         Py_RETURN_NONE;
534 }
535
536 static char BPy_StringProperty_doc[] =
537 ".. function:: StringProperty(name=\"\", description=\"\", default=\"\", maxlen=0, options={'ANIMATABLE'}, subtype='NONE')\n"
538 "\n"
539 "   Returns a new string property definition.\n"
540 "\n"
541 BPY_PROPDEF_NAME_DOC
542 BPY_PROPDEF_DESC_DOC
543 "   :arg options: Enumerator in ['HIDDEN', 'ANIMATABLE'].\n"
544 "   :type options: set\n"
545 "   :arg subtype: Enumerator in ['FILE_PATH', 'DIR_PATH', 'FILENAME', 'NONE'].\n"
546 "   :type subtype: string\n"
547 ;
548 static PyObject *BPy_StringProperty(PyObject *self, PyObject *args, PyObject *kw)
549 {
550         StructRNA *srna;
551
552         BPY_PROPDEF_HEAD(StringProperty)
553
554         if(srna) {
555                 static const char *kwlist[] = {"attr", "name", "description", "default", "maxlen", "options", "subtype", NULL};
556                 const char *id=NULL, *name="", *description="", *def="";
557                 int id_len;
558                 int maxlen=0;
559                 PropertyRNA *prop;
560                 PyObject *pyopts= NULL;
561                 int opts=0;
562                 char *pysubtype= NULL;
563                 int subtype= PROP_NONE;
564
565                 if (!PyArg_ParseTupleAndKeywords(args, kw, "s#|sssiO!s:StringProperty", (char **)kwlist, &id, &id_len, &name, &description, &def, &maxlen, &PySet_Type, &pyopts, &pysubtype))
566                         return NULL;
567
568                 BPY_PROPDEF_SUBTYPE_CHECK(StringProperty, property_flag_items, property_subtype_string_items)
569
570                 prop= RNA_def_property(srna, id, PROP_STRING, subtype);
571                 if(maxlen != 0) RNA_def_property_string_maxlength(prop, maxlen + 1); /* +1 since it includes null terminator */
572                 if(def) RNA_def_property_string_default(prop, def);
573                 RNA_def_property_ui_text(prop, name, description);
574
575                 if(pyopts) {
576                         if(opts & PROP_HIDDEN) RNA_def_property_flag(prop, PROP_HIDDEN);
577                         if((opts & PROP_ANIMATABLE)==0) RNA_def_property_clear_flag(prop, PROP_ANIMATABLE);
578                 }
579                 RNA_def_property_duplicate_pointers(srna, prop);
580         }
581         Py_RETURN_NONE;
582 }
583
584 static EnumPropertyItem *enum_items_from_py(PyObject *seq_fast, PyObject *def, int *defvalue, const short is_enum_flag)
585 {
586         EnumPropertyItem *items= NULL;
587         PyObject *item;
588         int seq_len, i, totitem= 0;
589         short def_used= 0;
590         const char *def_cmp= NULL;
591
592         seq_len= PySequence_Fast_GET_SIZE(seq_fast);
593
594         if(is_enum_flag) {
595                 if(seq_len > RNA_ENUM_BITFLAG_SIZE) {
596                         PyErr_SetString(PyExc_TypeError, "EnumProperty(...): maximum " STRINGIFY(RNA_ENUM_BITFLAG_SIZE) " members for a ENUM_FLAG type property");
597                         return NULL;
598                 }
599                 if(def && !PySet_Check(def)) {
600                         PyErr_Format(PyExc_TypeError, "EnumProperty(...): default option must be a 'set' type when ENUM_FLAG is enabled, not a '%.200s'", Py_TYPE(def)->tp_name);
601                         return NULL;
602                 }
603         }
604         else {
605                 if(def) {
606                         def_cmp= _PyUnicode_AsString(def);
607                         if(def_cmp==NULL) {
608                                 PyErr_Format(PyExc_TypeError, "EnumProperty(...): default option must be a 'str' type when ENUM_FLAG is disabled, not a '%.200s'", Py_TYPE(def)->tp_name);
609                                 return NULL;
610                         }
611                 }
612         }
613
614         /* blank value */
615         *defvalue= 0;
616
617         for(i=0; i<seq_len; i++) {
618                 EnumPropertyItem tmp= {0, "", 0, "", ""};
619
620                 item= PySequence_Fast_GET_ITEM(seq_fast, i);
621                 if(PyTuple_Check(item)==0) {
622                         PyErr_SetString(PyExc_TypeError, "EnumProperty(...): expected a sequence of tuples for the enum items");
623                         if(items) MEM_freeN(items);
624                         return NULL;
625                 }
626
627                 if(!PyArg_ParseTuple(item, "sss", &tmp.identifier, &tmp.name, &tmp.description)) {
628                         PyErr_SetString(PyExc_TypeError, "EnumProperty(...): expected an identifier, name and description in the tuple");
629                         return NULL;
630                 }
631
632                 if(is_enum_flag) {
633                         tmp.value= 1<<i;
634
635                         if(def && PySet_Contains(def, PyTuple_GET_ITEM(item, 0))) {
636                                 *defvalue |= tmp.value;
637                                 def_used++;
638                         }
639                 }
640                 else {
641                         tmp.value= i;
642
643                         if(def && def_used == 0 && strcmp(def_cmp, tmp.identifier)==0) {
644                                 *defvalue= tmp.value;
645                                 def_used++; /* only ever 1 */
646                         }
647                 }
648
649                 RNA_enum_item_add(&items, &totitem, &tmp);
650         }
651
652         RNA_enum_item_end(&items, &totitem);
653
654         if(is_enum_flag) {
655                 /* strict check that all set members were used */
656                 if(def && def_used != PySet_GET_SIZE(def)) {
657                         MEM_freeN(items);
658
659                         PyErr_Format(PyExc_TypeError, "EnumProperty(..., default={...}): set has %d unused member(s)", PySet_GET_SIZE(def) - def_used);
660                         return NULL;
661                 }
662         }
663         else {
664                 if(def && def_used == 0) {
665                         MEM_freeN(items);
666
667                         PyErr_Format(PyExc_TypeError, "EnumProperty(..., default=\'%s\'): not found in enum members", def);
668                         return NULL;
669                 }
670         }
671
672         return items;
673 }
674
675 static char BPy_EnumProperty_doc[] =
676 ".. function:: EnumProperty(items, name=\"\", description=\"\", default=\"\", options={'ANIMATABLE'})\n"
677 "\n"
678 "   Returns a new enumerator property definition.\n"
679 "\n"
680 BPY_PROPDEF_NAME_DOC
681 BPY_PROPDEF_DESC_DOC
682 "   :arg default: The default value for this enum, A string when *ENUM_FLAG* is disabled otherwise a set which may only contain string identifiers used in *items*.\n"
683 "   :type default: string or set\n"
684 "   :arg options: Enumerator in ['HIDDEN', 'ANIMATABLE', 'ENUM_FLAG'].\n"
685 "   :type options: set\n"
686 "   :arg items: sequence of enum items formatted: [(identifier, name, description), ...] where the identifier is used for python access and other values are used for the interface.\n"
687 "   :type items: sequence of string triplets\n"
688 ;
689 static PyObject *BPy_EnumProperty(PyObject *self, PyObject *args, PyObject *kw)
690 {
691         StructRNA *srna;
692
693         BPY_PROPDEF_HEAD(EnumProperty)
694         
695         if(srna) {
696                 static const char *kwlist[] = {"attr", "items", "name", "description", "default", "options", NULL};
697                 const char *id=NULL, *name="", *description="";
698                 PyObject *def= NULL;
699                 int id_len;
700                 int defvalue=0;
701                 PyObject *items, *items_fast;
702                 EnumPropertyItem *eitems;
703                 PropertyRNA *prop;
704                 PyObject *pyopts= NULL;
705                 int opts=0;
706
707                 if (!PyArg_ParseTupleAndKeywords(args, kw, "s#O|ssOO!:EnumProperty", (char **)kwlist, &id, &id_len, &items, &name, &description, &def, &PySet_Type, &pyopts))
708                         return NULL;
709
710                 BPY_PROPDEF_CHECK(EnumProperty, property_flag_enum_items)
711
712                 if(!(items_fast= PySequence_Fast(items, "EnumProperty(...): expected a sequence of tuples for the enum items"))) {
713                         return NULL;
714                 }
715
716                 eitems= enum_items_from_py(items_fast, def, &defvalue, (opts & PROP_ENUM_FLAG)!=0);
717
718                 Py_DECREF(items_fast);
719
720                 if(!eitems)
721                         return NULL;
722
723                 if(opts & PROP_ENUM_FLAG)       prop= RNA_def_enum_flag(srna, id, eitems, defvalue, name, description);
724                 else                                            prop= RNA_def_enum(srna, id, eitems, defvalue, name, description);
725
726                 if(pyopts) {
727                         if(opts & PROP_HIDDEN) RNA_def_property_flag(prop, PROP_HIDDEN);
728                         if((opts & PROP_ANIMATABLE)==0) RNA_def_property_clear_flag(prop, PROP_ANIMATABLE);
729                 }
730                 RNA_def_property_duplicate_pointers(srna, prop);
731                 MEM_freeN(eitems);
732         }
733         Py_RETURN_NONE;
734 }
735
736 static StructRNA *pointer_type_from_py(PyObject *value, const char *error_prefix)
737 {
738         StructRNA *srna;
739
740         srna= srna_from_self(value, "");
741         if(!srna) {
742                 if(PyErr_Occurred()) {
743                         PyObject *msg= PyC_ExceptionBuffer();
744                         char *msg_char= _PyUnicode_AsString(msg);
745                         PyErr_Format(PyExc_TypeError, "%.200s expected an RNA type derived from PropertyGroup, failed with: %s", error_prefix, msg_char);
746                         Py_DECREF(msg);
747                 }
748                 else {
749                         PyErr_Format(PyExc_TypeError, "%.200s expected an RNA type derived from PropertyGroup, failed with type '%s'", error_prefix, Py_TYPE(value)->tp_name);
750                 }
751                 return NULL;
752         }
753
754         if(!RNA_struct_is_a(srna, &RNA_PropertyGroup)) {
755                  PyErr_Format(PyExc_TypeError, "%.200s expected an RNA type derived from PropertyGroup", error_prefix);
756                 return NULL;
757         }
758
759         return srna;
760 }
761
762 static char BPy_PointerProperty_doc[] =
763 ".. function:: PointerProperty(type=\"\", description=\"\", options={'ANIMATABLE'})\n"
764 "\n"
765 "   Returns a new pointer property definition.\n"
766 "\n"
767 "   :arg type: A subclass of :class:`bpy.types.PropertyGroup`.\n"
768 "   :type type: class\n"
769 BPY_PROPDEF_NAME_DOC
770 BPY_PROPDEF_DESC_DOC
771 "   :arg options: Enumerator in ['HIDDEN', 'ANIMATABLE'].\n"
772 "   :type options: set\n"
773 ;
774 static PyObject *BPy_PointerProperty(PyObject *self, PyObject *args, PyObject *kw)
775 {
776         StructRNA *srna;
777
778         BPY_PROPDEF_HEAD(PointerProperty)
779
780         if(srna) {
781                 static const char *kwlist[] = {"attr", "type", "name", "description", "options", NULL};
782                 const char *id=NULL, *name="", *description="";
783                 int id_len;
784                 PropertyRNA *prop;
785                 StructRNA *ptype;
786                 PyObject *type= Py_None;
787                 PyObject *pyopts= NULL;
788                 int opts=0;
789
790                 if (!PyArg_ParseTupleAndKeywords(args, kw, "s#O|ssO!:PointerProperty", (char **)kwlist, &id, &id_len, &type, &name, &description, &PySet_Type, &pyopts))
791                         return NULL;
792
793                 BPY_PROPDEF_CHECK(PointerProperty, property_flag_items)
794
795                 ptype= pointer_type_from_py(type, "PointerProperty(...):");
796                 if(!ptype)
797                         return NULL;
798
799                 prop= RNA_def_pointer_runtime(srna, id, ptype, name, description);
800                 if(pyopts) {
801                         if(opts & PROP_HIDDEN) RNA_def_property_flag(prop, PROP_HIDDEN);
802                         if((opts & PROP_ANIMATABLE)==0) RNA_def_property_clear_flag(prop, PROP_ANIMATABLE);
803                 }
804                 RNA_def_property_duplicate_pointers(srna, prop);
805         }
806         Py_RETURN_NONE;
807 }
808
809 static char BPy_CollectionProperty_doc[] =
810 ".. function:: CollectionProperty(items, type=\"\", description=\"\", default=\"\", options={'ANIMATABLE'})\n"
811 "\n"
812 "   Returns a new collection property definition.\n"
813 "\n"
814 "   :arg type: A subclass of :class:`bpy.types.PropertyGroup`.\n"
815 "   :type type: class\n"
816 BPY_PROPDEF_NAME_DOC
817 BPY_PROPDEF_DESC_DOC
818 "   :arg options: Enumerator in ['HIDDEN', 'ANIMATABLE'].\n"
819 "   :type options: set\n"
820 ;
821 static PyObject *BPy_CollectionProperty(PyObject *self, PyObject *args, PyObject *kw)
822 {
823         StructRNA *srna;
824
825         BPY_PROPDEF_HEAD(CollectionProperty)
826
827         if(srna) {
828                 static const char *kwlist[] = {"attr", "type", "name", "description", "options", NULL};
829                 const char *id=NULL, *name="", *description="";
830                 int id_len;
831                 PropertyRNA *prop;
832                 StructRNA *ptype;
833                 PyObject *type= Py_None;
834                 PyObject *pyopts= NULL;
835                 int opts=0;
836
837                 if (!PyArg_ParseTupleAndKeywords(args, kw, "s#O|ssO!:CollectionProperty", (char **)kwlist, &id, &id_len, &type, &name, &description, &PySet_Type, &pyopts))
838                         return NULL;
839
840                 BPY_PROPDEF_CHECK(CollectionProperty, property_flag_items)
841
842                 ptype= pointer_type_from_py(type, "CollectionProperty(...):");
843                 if(!ptype)
844                         return NULL;
845
846                 prop= RNA_def_collection_runtime(srna, id, ptype, name, description);
847                 if(pyopts) {
848                         if(opts & PROP_HIDDEN) RNA_def_property_flag(prop, PROP_HIDDEN);
849                         if((opts & PROP_ANIMATABLE)==0) RNA_def_property_clear_flag(prop, PROP_ANIMATABLE);
850                 }
851                 RNA_def_property_duplicate_pointers(srna, prop);
852         }
853         Py_RETURN_NONE;
854 }
855
856 static char BPy_RemoveProperty_doc[] =
857 ".. function:: RemoveProperty(attr)\n"
858 "\n"
859 "   Removes a dynamically defined property.\n"
860 "\n"
861 "   :arg attr: Property name.\n"
862 "   :type attr: string\n"
863 ;
864 static PyObject *BPy_RemoveProperty(PyObject *self, PyObject *args, PyObject *kw)
865 {
866         StructRNA *srna;
867
868         if(PyTuple_GET_SIZE(args) == 1) {
869                 PyObject *ret;
870                 self= PyTuple_GET_ITEM(args, 0);
871                 args= PyTuple_New(0);
872                 ret= BPy_RemoveProperty(self, args, kw);
873                 Py_DECREF(args);
874                 return ret;     
875         }
876         else if (PyTuple_GET_SIZE(args) > 1) {
877                  PyErr_SetString(PyExc_ValueError, "all args must be keywords"); \
878                 return NULL;
879         }
880
881         srna= srna_from_self(self, "RemoveProperty(...):");
882         if(srna==NULL && PyErr_Occurred()) {
883                 return NULL; /* self's type was compatible but error getting the srna */
884         }
885         else if(srna==NULL) {
886                 PyErr_SetString(PyExc_TypeError, "RemoveProperty(): struct rna not available for this type");
887                 return NULL;
888         }
889         else {
890                 static const char *kwlist[] = {"attr", NULL};
891                 
892                 char *id=NULL;
893
894                 if (!PyArg_ParseTupleAndKeywords(args, kw, "s:RemoveProperty", (char **)kwlist, &id))
895                         return NULL;
896
897                 if(RNA_def_property_free_identifier(srna, id) != 1) {
898                         PyErr_Format(PyExc_TypeError, "RemoveProperty(): '%s' not a defined dynamic property", id);
899                         return NULL;
900                 }
901         }
902         Py_RETURN_NONE;
903 }
904
905 static struct PyMethodDef props_methods[] = {
906         {"BoolProperty", (PyCFunction)BPy_BoolProperty, METH_VARARGS|METH_KEYWORDS, BPy_BoolProperty_doc},
907         {"BoolVectorProperty", (PyCFunction)BPy_BoolVectorProperty, METH_VARARGS|METH_KEYWORDS, BPy_BoolVectorProperty_doc},
908         {"IntProperty", (PyCFunction)BPy_IntProperty, METH_VARARGS|METH_KEYWORDS, BPy_IntProperty_doc},
909         {"IntVectorProperty", (PyCFunction)BPy_IntVectorProperty, METH_VARARGS|METH_KEYWORDS, BPy_IntVectorProperty_doc},
910         {"FloatProperty", (PyCFunction)BPy_FloatProperty, METH_VARARGS|METH_KEYWORDS, BPy_FloatProperty_doc},
911         {"FloatVectorProperty", (PyCFunction)BPy_FloatVectorProperty, METH_VARARGS|METH_KEYWORDS, BPy_FloatVectorProperty_doc},
912         {"StringProperty", (PyCFunction)BPy_StringProperty, METH_VARARGS|METH_KEYWORDS, BPy_StringProperty_doc},
913         {"EnumProperty", (PyCFunction)BPy_EnumProperty, METH_VARARGS|METH_KEYWORDS, BPy_EnumProperty_doc},
914         {"PointerProperty", (PyCFunction)BPy_PointerProperty, METH_VARARGS|METH_KEYWORDS, BPy_PointerProperty_doc},
915         {"CollectionProperty", (PyCFunction)BPy_CollectionProperty, METH_VARARGS|METH_KEYWORDS, BPy_CollectionProperty_doc},
916
917         {"RemoveProperty", (PyCFunction)BPy_RemoveProperty, METH_VARARGS|METH_KEYWORDS, BPy_RemoveProperty_doc},
918         {NULL, NULL, 0, NULL}
919 };
920
921 static struct PyModuleDef props_module = {
922         PyModuleDef_HEAD_INIT,
923         "bpy.props",
924         "This module defines properties to extend blenders internal data, the result of these functions"
925         " is used to assign properties to classes registered with blender and can't be used directly.",
926         -1,/* multiple "initialization" just copies the module dict. */
927         props_methods,
928         NULL, NULL, NULL, NULL
929 };
930
931 PyObject *BPY_rna_props( void )
932 {
933         PyObject *submodule;
934         PyObject *submodule_dict;
935         
936         submodule= PyModule_Create(&props_module);
937         PyDict_SetItemString(PyImport_GetModuleDict(), props_module.m_name, submodule);
938
939         /* INCREF since its its assumed that all these functions return the
940          * module with a new ref like PyDict_New, since they are passed to
941           * PyModule_AddObject which steals a ref */
942         Py_INCREF(submodule);
943         
944         /* api needs the PyObjects internally */
945         submodule_dict= PyModule_GetDict(submodule);
946
947 #define ASSIGN_STATIC(_name) pymeth_##_name = PyDict_GetItemString(submodule_dict, #_name)
948
949         ASSIGN_STATIC(BoolProperty);
950         ASSIGN_STATIC(BoolVectorProperty);
951         ASSIGN_STATIC(IntProperty);
952         ASSIGN_STATIC(IntVectorProperty);
953         ASSIGN_STATIC(FloatProperty);
954         ASSIGN_STATIC(FloatVectorProperty);
955         ASSIGN_STATIC(StringProperty);
956         ASSIGN_STATIC(EnumProperty);
957         ASSIGN_STATIC(PointerProperty);
958         ASSIGN_STATIC(CollectionProperty);
959         ASSIGN_STATIC(RemoveProperty);
960         
961         return submodule;
962 }