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