Attempted to unify and document Dupli* stuff.

DupGroup
DupObjects
enableDupVerts
enableDupFrames
enableDupGroup
enableDupRot
enableDupNoSpeed

see the epydocs for documentation at http://members.iinet.net.au/~cpbarton/ideasman/BPY_API/Object.Object-class.html - will update in a tick.

2 files changed, 99 insertions, 124 deletions

diff --git a/source/blender/python/api2_2x/Object.c b/source/blender/python/api2_2x/Object.c
index 59f78349c67..f665be08550 100644
--- a/source/blender/python/api2_2x/Object.c
+++ b/source/blender/python/api2_2x/Object.c
@@ -219,7 +219,7 @@ static PyObject *Object_join( BPy_Object * self, PyObject * args );
 static PyObject *Object_makeParentDeform( BPy_Object * self, PyObject * args );
 static PyObject *Object_makeParentVertex( BPy_Object * self, PyObject * args );
 static PyObject *Object_materialUsage( void );
-static PyObject *Object_getDupliVerts ( BPy_Object * self );
+static PyObject *Object_getDupliVerts ( BPy_Object * self ); /* */
 static PyObject *Object_getDupliFrames ( BPy_Object * self );
 static PyObject *Object_getDupliGroup ( BPy_Object * self );
 static PyObject *Object_getDupliRot ( BPy_Object * self );
@@ -256,11 +256,11 @@ static PyObject *Object_copyAllPropertiesTo( BPy_Object * self,
 static PyObject *Object_getScriptLinks( BPy_Object * self, PyObject * args );
 static PyObject *Object_addScriptLink( BPy_Object * self, PyObject * args );
 static PyObject *Object_clearScriptLinks( BPy_Object * self, PyObject *args );
-static PyObject *Object_setDupliVerts ( BPy_Object * self, PyObject * args );
-static PyObject *Object_setDupliFrames ( BPy_Object * self, PyObject * args );
-static PyObject *Object_setDupliGroup ( BPy_Object * self, PyObject * args );
-static PyObject *Object_setDupliRot ( BPy_Object * self , PyObject * args);
-static PyObject *Object_setDupliNoSpeed ( BPy_Object * self , PyObject * args);
+static PyObject *Object_setDupliVerts ( BPy_Object * self, PyObject * args ); /* removed from API, used by enableDupliVerts */
+static PyObject *Object_setDupliFrames ( BPy_Object * self, PyObject * args ); /* removed from API, used by enableDupliFrames */
+static PyObject *Object_setDupliGroup ( BPy_Object * self, PyObject * args ); /* removed from API, used by enableDupliGroups */
+static PyObject *Object_setDupliRot ( BPy_Object * self , PyObject * args); /* removed from API, used by enableDupliRot */
+static PyObject *Object_setDupliNoSpeed ( BPy_Object * self , PyObject * args); /* removed from API, used by enableDupliNoSpeed */
 static PyObject *Object_getPIStrength( BPy_Object * self );
 static PyObject *Object_setPIStrength( BPy_Object * self, PyObject * args );
 static PyObject *Object_getPIFalloff( BPy_Object * self );
@@ -482,19 +482,9 @@ automatic when the script finishes."},
 	 "Sets SB StiffQuads"},
 	{"getBoundBox", ( PyCFunction ) Object_getBoundBox, METH_NOARGS,
 	 "Returns the object's bounding box"},
-	{"getDupliVerts", ( PyCFunction ) Object_getDupliVerts,
-	 METH_VARARGS, "Returns state of duplicates propertie"},
-	{"getDupliFrames", ( PyCFunction ) Object_getDupliFrames,
-	 METH_NOARGS, "Returns state of Frames duplicates propertie"},
-	{"getDupliGroup", ( PyCFunction ) Object_getDupliGroup,
-	 METH_NOARGS, "Returns state of Group duplicates propertie"},
-	{"getDupliRot", ( PyCFunction ) Object_getDupliRot,
-	 METH_NOARGS, "Returns state of Rot duplicates propertie"},
-	{"getDupliNoSpeed", ( PyCFunction ) Object_getDupliNoSpeed,
-	 METH_NOARGS, "Returns state of Nospeed duplicates propertie"},
-	{"getDupliObjects", ( PyCFunction ) Object_getDupliObjects,
+	/*{"getDupliObjects", ( PyCFunction ) Object_getDupliObjects,
 	 METH_NOARGS, "Returns of list of tuples for object duplicated (object, dupliMatrix)\n\
-	 by dupliframe or dupliverst state "},
+	 by dupliframe or dupliverst state "},*/
 	{"makeDisplayList", ( PyCFunction ) Object_makeDisplayList,
 	 METH_NOARGS,
 	 "Update this object's Display List. Some changes like turning \n\
@@ -619,16 +609,6 @@ works only if self and the object specified are of the same type."},
 	 METH_VARARGS,
 	 "() - Delete all scriptlinks from this object.\n"
 	 "([s1<,s2,s3...>]) - Delete specified scriptlinks from this object."},
-	{"setDupliVerts", ( PyCFunction ) Object_setDupliVerts,
-	 METH_VARARGS, "() - set or reset duplicate child objects on all vertices"},
-	{"setDupliFrames", ( PyCFunction ) Object_setDupliFrames,
-	 METH_VARARGS, "- set or reset state of Frames duplicates propertie"},
-	{"setDupliGroup", ( PyCFunction ) Object_setDupliGroup,
-	 METH_VARARGS, "- set or reset state of Group duplicates propertie"},
-	{"setDupliRot", ( PyCFunction ) Object_setDupliRot,
-	 METH_VARARGS, "- set or reset state of Rot duplicates propertie"},
-	{"setDupliNoSpeed", ( PyCFunction ) Object_setDupliNoSpeed,
-	 METH_VARARGS, "- set or reset state of Nospeed duplicates propertie"},
 	{"insertShapeKey", ( PyCFunction ) Object_insertShapeKey,
 	 METH_NOARGS, "() - Insert a Shape Key in the current object"},
 	{NULL, NULL, 0, NULL}
@@ -3523,8 +3503,20 @@ static PyObject *Object_getAttr( BPy_Object * obj, char *name )
 		return PyInt_FromLong( obj->object->id.us );
 	if( StringEqual( name, "protectFlags" ) )
 		return PyInt_FromLong( obj->object->protectflag );
-	if( StringEqual( name, "dupliGroup" ) )
+	if( StringEqual( name, "DupObjects" ) )
+		return Object_getDupliObjects( obj );
+	if( StringEqual( name, "DupGroup" ) )
 		return Group_CreatePyObject( obj->object->dup_group );
+	if( StringEqual( name, "enableDupVerts" ) )
+		return Object_getDupliVerts( obj );
+	if( StringEqual( name, "enableDupFrames" ) )
+		return Object_getDupliFrames( obj );
+	if( StringEqual( name, "enableDupGroup" ) )
+		return Object_getDupliGroup( obj );
+	if( StringEqual( name, "enableDupRot" ) )
+		return Object_getDupliRot( obj );
+	if( StringEqual( name, "enableDupNoSpeed" ) )
+		return Object_getDupliNoSpeed( obj );	
 	
 	/* not an attribute, search the methods table */
 	return Py_FindMethod( BPy_Object_methods, ( PyObject * ) obj, name );
@@ -3540,7 +3532,7 @@ static int Object_setAttr( BPy_Object * obj, char *name, PyObject * value )
 {
 	PyObject *valtuple, *result=NULL;
 	struct Object *object;
-
+	
 	object = obj->object;
 
 	/* Handle all properties which are Read Only */
@@ -3744,17 +3736,21 @@ static int Object_setAttr( BPy_Object * obj, char *name, PyObject * value )
 		object->protectflag = (short)flag;
 		return 0;
 	}
-	if( StringEqual( name, "dupliGroup" ) ) {
+	if( StringEqual( name, "DupGroup" ) ) {
 		PyObject *pyob=NULL;
 		BPy_Group *pygrp=NULL;
 		if( !PyArg_Parse( value, "O", &pyob) )
 			return EXPP_ReturnIntError( PyExc_TypeError,
-							"expected a group" );	
-		if (pyob==Py_None) {
-			object->dup_group= NULL;
-		} else {
+							"expected a group or None" );	
+		
+		if ( PyObject_TypeCheck(pyob, &Group_Type) ) {
 			pygrp= (BPy_Group *)pyob;
 			object->dup_group= pygrp->group;
+		} else if (pyob==Py_None) {
+			object->dup_group= NULL;
+		} else {
+			return EXPP_ReturnIntError( PyExc_TypeError,
+							"expected a group or None" );
 		}
 		return 0;
 	}
@@ -3789,6 +3785,20 @@ static int Object_setAttr( BPy_Object * obj, char *name, PyObject * value )
 	else if( StringEqual( name, "effects" ) )
 		return EXPP_ReturnIntError( PyExc_AttributeError, 
 				"effects is not writable" );
+	
+	else if( StringEqual( name, "enableDupVerts" ) )
+		result = Object_setDupliVerts( obj, valtuple );
+	else if( StringEqual( name, "enableDupFrames" ) )
+		result = Object_setDupliFrames( obj, valtuple );
+	else if( StringEqual( name, "enableDupGroup" ) )
+		result = Object_setDupliGroup( obj, valtuple );
+	else if( StringEqual( name, "enableDupRot" ) )
+		result = Object_setDupliRot( obj, valtuple );
+	else if( StringEqual( name, "enableDupNoSpeed" ) )
+		result = Object_setDupliNoSpeed( obj, valtuple );	
+	else if( StringEqual( name, "DupObjects" ) )
+		return EXPP_ReturnIntError( PyExc_AttributeError, 
+				"DupObjects is not writable" );
 	else { /* if it turns out here, it's not an attribute*/
 		Py_DECREF(valtuple);
 		return EXPP_ReturnIntError( PyExc_KeyError, "attribute not found" );
diff --git a/source/blender/python/api2_2x/doc/Object.py b/source/blender/python/api2_2x/doc/Object.py
index 5669728e2f7..971cd38bd3a 100644
--- a/source/blender/python/api2_2x/doc/Object.py
+++ b/source/blender/python/api2_2x/doc/Object.py
@@ -247,7 +247,7 @@ class Object:
     @ivar sel: The selection state of the object in the current scene, 1 is selected, 0 is unselected. (Selecting makes the object active)
     @ivar effects: The list of particle effects associated with the object.  (Read-only)
     @ivar parentbonename: The string name of the parent bone.
-    @ivar users: The number of users of the object.  Read-only.
+    @ivar users: The number of users of the object.  (Read-only)
     @type users: int
     @ivar protectFlags: The "transform locking" bitfield flags for the object.  
     Setting bits lock the following attributes:
@@ -261,11 +261,61 @@ class Object:
        - bit 7: Y size
        - bit 8: Z size
     @type protectFlags: int
-    @ivar dupliGroup: The dupli group that this object is an instance of.
-        This does not enable or disable the dupligroup option, for that use
+    @ivar DupGroup: The DupliGroup Animation Property.
+        Assign a group to DupGroup to make this object an instance of that group.
+        This does not enable or disable the dupliGroup option, for that use
         getDupliGroup and setDupliGroup.
         The dupliGroup is None when this object does not have a dupliGroup.
-    @type dupliGroup: list of integers
+        (Use with L{enableDupGroup<enableDupGroup>})
+    @type DupGroup: Group or None
+    @ivar DupObjects: The Dupli object instances. Returns of list of tuples for object duplicated
+        by dupliframe, dupliverts dupligroups and other animation properties.
+        The first item is the original object that is duplicated
+        the second is the 4x4 worldspace dupli-matrix.
+        Example::
+         import Blender
+         from Blender import Object, Scene, Mathutils
+
+         ob= Object.Get('Cube')
+         dupe_obs= ob.getDupliObjects()
+         scn= Scene.GetCurrent()
+         for dupe_ob, dupe_matrix in dupe_obs:
+           print dupe_ob.name
+           empty_ob= Object.New('Empty')
+           scn.link(empty_ob)
+           empty_ob.setMatrix(dupe_matrix)
+         Blender.Redraw()
+        (Read-only)
+    @type DupObjects: list of tuples (object, matrix)
+    @ivar enableDupVerts: The DupliVerts status of the object.
+        True/False - does not indicate that this object has any dupliVerts,
+        (as returned by DupObjects) just that dupliVerts are enabled.
+    @type enableDupVerts: bool (True/False)
+    @ivar enableDupFrames: The DupliFrames status of the object.
+        True/False - does not indicate that this object has any dupliFrames,
+        (as returned by DupObjects) just that dupliFrames are enabled.
+    @type enableDupFrames: bool (True/False)
+    @ivar enableDupGroup: The DupliFroup status of the object.
+        True/False - Set DupGroup to a group for this to take effect,
+        Use DupObjects to get the object data from this instance. (Use with L{DupObjects<DupObjects>})
+    @type enableDupGroup: bool (True/False)
+    @ivar enableDupRot: The DupliRot status of the object.
+        True/False - Use with enableDupVerts to rotate each instance
+        by the vertex normal. (Use with L{enableDupVerts<enableDupVerts>})
+    @type enableDupRot: bool (True/False)
+    @ivar enableDupNoSpeed: The DupliNoSpeed status of the object.
+        True/False - Use with enableDupFrames to ignore
+        dupliFrame speed. (Use with L{enableDupFrames<enableDupFrames>})
+    @type enableDupNoSpeed: bool (True/False)
+    @ivar DupSta: The DupliFrame starting frame. (Use with L{enableDupFrames<enableDupFrames>})
+    @type DupSta: int
+    @ivar DupEnd: The DupliFrame end frame. (Use with L{enableDupFrames<enableDupFrames>})
+    @type DupEnd: int
+    @ivar DupOn: The DupliFrames in sucsession between DupOff frames.
+        (Use with L{enableDupFrames<enableDupFrames>} and L{DupOff<DupOff>} > 0)
+    @type DupOn: int
+    @ivar DupOff: The DupliFrame removal of every Nth frame for this object. (Use with L{enableDupFrames<enableDupFrames>})
+    @type DupOff: int
   """
 
   def buildParts():
@@ -516,61 +566,6 @@ class Object:
         Blender.Redraw()
     """
 
-  def getDupliVerts():
-    """
-    Get state of DupliVerts animation property
-    @return: a boolean value.
-    """
-
-  def getDupliFrames():
-    """
-    Get state of DupliFrames animation property
-    @return: a boolean value.
-    """
-
-  def getDupliGroup():
-    """
-    Get state of DupliGroup animation property
-    @note: This does not return the group used or that there is a dupli group set for this object. Only that dupliGroup is enabled.
-    @return: a boolean value.
-    """
-    
-  def getDupliRot():
-    """
-    Get state of DupliRot animation property
-    @return: a boolean value.
-    """
-    
-  def getDupliNoSpeed():
-    """
-    Get state of DupliRot animation property
-    @return: a boolean value.
-    """
-    
-  def getDupliObjects():
-    """
-    Returns of list of tuples for object duplicated
-    by dupliframe, dupliverts dupligroups and animation functions.
-    The first item is the original object that is duplicated
-    the second is the 4x4 worldspace dupli-matrix.
-    @rtype: List
-    @return: list of tuples (object, matrix)
-    Example::
-     import Blender
-     from Blender import Object, Scene, Mathutils
-
-     ob= Object.Get('Cube')
-     dupe_obs= ob.getDupliObjects()
-     scn= Scene.GetCurrent()
-     for dupe_ob, dupe_matrix in dupe_obs:
-       print dupe_ob.name
-       empty_ob= Object.New('Empty')
-       scn.link(empty_ob)
-       empty_ob.setMatrix(dupe_matrix)
-     Blender.Redraw()
-    """
-
-
   def insertIpoKey(keytype):
     """
     Inserts keytype values in object ipo at curframe. Uses module constants.
@@ -957,36 +952,6 @@ class Object:
     @param object: Object that will receive the properties.
     """
 
-  def setDupliVerts(data):
-    """
-    Set state of DupliVerts animation property
-    @param data: boolean value True/False, non zero/zero.
-    """
-
-  def setDupliFrames(data):
-    """
-    Set state of DupliFrames animation property
-    @param data: boolean value True/False, non zero/zero.
-    """
-
-  def setDupliGroups(data):
-    """
-    Set state of DupliGroup animation property, this does not set the group used. 
-    @param data: boolean value True/False, non zero/zero.
-    """
-
-  def setDupliRot(data):
-    """
-    Set state of DupliRot animation property
-    @param data: boolean value True/False, non zero/zero.
-    """
-    
-  def setDupliNoSpeed (data):
-    """
-    Set state of DupliNoSpeed animation property
-     @param data: boolean value True/False, non zero/zero.
-     """
-
   def getPIStregth():
     """
     Get the Object's Particle Interaction Strength.