- Updated BGE docs to match the game engines class inheritance more closely.

- Grouped deprecated functions for KX_Camera, KX_GameObject, SCA_ISensor, SCA_ILogicBrick, KX_Scene

17 files changed, 100 insertions, 15 deletions

diff --git a/source/gameengine/PyDoc/BL_Shader.py b/source/gameengine/PyDoc/BL_Shader.py
index 182b73d437b..10e8b7c94ef 100644
--- a/source/gameengine/PyDoc/BL_Shader.py
+++ b/source/gameengine/PyDoc/BL_Shader.py
@@ -1,4 +1,7 @@
-class BL_Shader: # (PyObjectPlus)
+
+from PyObjectPlus import *
+
+class BL_Shader(PyObjectPlus):
 	"""
 	BL_Shader GLSL shaders.
 	
diff --git a/source/gameengine/PyDoc/CListValue.py b/source/gameengine/PyDoc/CListValue.py
index e9fc4215bb6..1f60e8a7bc2 100644
--- a/source/gameengine/PyDoc/CListValue.py
+++ b/source/gameengine/PyDoc/CListValue.py
@@ -1,4 +1,6 @@
-class CListValue: # (PyObjectPlus)
+from CPropValue import *
+
+class CListValue(CPropValue):
 	"""
 	CListValue
 	
diff --git a/source/gameengine/PyDoc/CPropValue.py b/source/gameengine/PyDoc/CPropValue.py
new file mode 100644
index 00000000000..498b47ab013
--- /dev/null
+++ b/source/gameengine/PyDoc/CPropValue.py
@@ -0,0 +1,8 @@
+# 
+# Documentation for CValue class
+from CValue import *
+class CPropValue(CValue):
+	"""
+	This class has no python functions
+	"""
+	pass
diff --git a/source/gameengine/PyDoc/CValue.py b/source/gameengine/PyDoc/CValue.py
new file mode 100644
index 00000000000..e9b0563955b
--- /dev/null
+++ b/source/gameengine/PyDoc/CValue.py
@@ -0,0 +1,8 @@
+# 
+# Documentation for CValue class
+from PyObjectPlus import *
+class CValue(PyObjectPlus):
+	"""
+	This class has no python functions
+	"""
+	pass
diff --git a/source/gameengine/PyDoc/KX_BlenderMaterial.py b/source/gameengine/PyDoc/KX_BlenderMaterial.py
index 21417db1802..c70a7dddcca 100644
--- a/source/gameengine/PyDoc/KX_BlenderMaterial.py
+++ b/source/gameengine/PyDoc/KX_BlenderMaterial.py
@@ -1,4 +1,7 @@
-class KX_BlenderMaterial: # (PyObjectPlus)
+
+from PyObjectPlus import *
+
+class KX_BlenderMaterial(PyObjectPlus): # , RAS_IPolyMaterial)
 	"""
 	KX_BlenderMaterial
 	
diff --git a/source/gameengine/PyDoc/KX_Camera.py b/source/gameengine/PyDoc/KX_Camera.py
index f5d0d45f968..5c54935192a 100644
--- a/source/gameengine/PyDoc/KX_Camera.py
+++ b/source/gameengine/PyDoc/KX_Camera.py
@@ -40,6 +40,8 @@ class KX_Camera(KX_GameObject):
 	                       Regenerated every frame from the camera's position and orientation.
 	                       This is camera_to_world inverted.
 	@type world_to_camera: 4x4 Matrix [[float]]
+	
+	@group Deprecated: enableViewport
 	"""
 	
 	def sphereInsideFrustum(centre, radius):
@@ -187,6 +189,7 @@ class KX_Camera(KX_GameObject):
 
 	def enableViewport(viewport):
 		"""
+		DEPRECATED: use the isViewport property
 		Use this camera to draw a viewport on the screen (for split screen games or overlay scenes). The viewport region is defined with L{setViewport}.
 		
 		@type viewport: bool
diff --git a/source/gameengine/PyDoc/KX_GameObject.py b/source/gameengine/PyDoc/KX_GameObject.py
index fcb3d91dbcb..2688de0d018 100644
--- a/source/gameengine/PyDoc/KX_GameObject.py
+++ b/source/gameengine/PyDoc/KX_GameObject.py
@@ -1,18 +1,18 @@
 # $Id$
 # Documentation for game objects
 
-# from SCA_IObject import *
+from SCA_IObject import *
 # from SCA_ISensor import *
 # from SCA_IController import *
 # from SCA_IActuator import *
 
 
-class KX_GameObject: # (SCA_IObject)
+class KX_GameObject(SCA_IObject):
 	"""
 	All game objects are derived from this class.
 	
 	Properties assigned to game objects are accessible as attributes of this class.
-		- note: Calling ANY method or attribute on an object that has been removed from a scene will raise a RuntimeError, if an object may have been removed since last accessing it use the L{isValid} attribute to check.
+		- note: Calling ANY method or attribute on an object that has been removed from a scene will raise a SystemError, if an object may have been removed since last accessing it use the L{invalid} attribute to check.
 
 	@ivar name: The object's name. (Read only)
 		- note: Currently (Blender 2.49) the prefix "OB" is added to all objects name. This may change in blender 2.5.
@@ -79,8 +79,7 @@ class KX_GameObject: # (SCA_IObject)
 		- note: This attribute is experemental and may be removed (but probably wont be).
 		- note: Changes to this list will not update the KX_GameObject.
 	@type actuators: list
-	@ivar isValid: Retuerns fails when the object has been removed from the scene and can no longer be used.
-	@type isValid: bool
+	@group Deprecated: getPosition, setPosition, setWorldPosition, getOrientation, setOrientation, getState, setState, getParent, getVisible, getMass, getMesh
 	"""
 	def endObject():
 		"""
diff --git a/source/gameengine/PyDoc/KX_MeshProxy.py b/source/gameengine/PyDoc/KX_MeshProxy.py
index e8839ac484c..c864523cde8 100644
--- a/source/gameengine/PyDoc/KX_MeshProxy.py
+++ b/source/gameengine/PyDoc/KX_MeshProxy.py
@@ -1,7 +1,9 @@
 # $Id$
 # Documentation for KX_MeshProxy
 
-class KX_MeshProxy:
+from SCA_IObject import *
+
+class KX_MeshProxy(SCA_IObject):
 	"""
 	A mesh object.
 	
diff --git a/source/gameengine/PyDoc/KX_PhysicsObjectWrapper.py b/source/gameengine/PyDoc/KX_PhysicsObjectWrapper.py
index 2171cf4c7b6..ea9a2a3a411 100644
--- a/source/gameengine/PyDoc/KX_PhysicsObjectWrapper.py
+++ b/source/gameengine/PyDoc/KX_PhysicsObjectWrapper.py
@@ -1,4 +1,6 @@
-class KX_PhysicsObjectWrapper: # (PyObjectPlus)
+from PyObjectPlus import *
+
+class KX_PhysicsObjectWrapper(PyObjectPlus):
 	"""
 	KX_PhysicsObjectWrapper
 	
diff --git a/source/gameengine/PyDoc/KX_PolyProxy.py b/source/gameengine/PyDoc/KX_PolyProxy.py
index bcd42c2ac2e..2d1c1f9b218 100644
--- a/source/gameengine/PyDoc/KX_PolyProxy.py
+++ b/source/gameengine/PyDoc/KX_PolyProxy.py
@@ -1,7 +1,8 @@
 # $Id$
 # Documentation for the polygon proxy class
+from SCA_IObject import *
 
-class KX_PolyProxy:
+class KX_PolyProxy(SCA_IObject):
 	"""
 	A polygon holds the index of the vertex forming the poylgon.
 
diff --git a/source/gameengine/PyDoc/KX_Scene.py b/source/gameengine/PyDoc/KX_Scene.py
index 5dcd560ee96..4fe150be898 100644
--- a/source/gameengine/PyDoc/KX_Scene.py
+++ b/source/gameengine/PyDoc/KX_Scene.py
@@ -1,7 +1,9 @@
 # $Id$
 # Documentation for KX_Scene.py
 
-class KX_Scene:
+from PyObjectPlus import *
+
+class KX_Scene(PyObjectPlus):
 	"""
 	Scene.
 	
@@ -41,6 +43,12 @@ class KX_Scene:
 	@type name: string
 	@ivar objects: A list of objects in the scene.
 	@type objects: L{CListValue<CListValue.CListValue>} of L{KX_GameObject<KX_GameObject.KX_GameObject>}
+	@ivar objects_inactive: A list of objects on background layers (used for the addObject actuator).
+	@type objects_inactive: L{CListValue<CListValue.CListValue>} of L{KX_GameObject<KX_GameObject.KX_GameObject>}
+	@ivar lights: A list of lights in the scene.
+	@type lights: L{CListValue<CListValue.CListValue>} of L{KX_GameObject<KX_LightObject.KX_LightObject>}
+	@ivar cameras: A list of cameras in the scene.
+	@type cameras: L{CListValue<CListValue.CListValue>} of L{KX_GameObject<KX_Camera.KX_Camera>}
 	@ivar active_camera: The current active camera
 	@type active_camera: L{KX_Camera}
 	@ivar suspended: True if the scene is suspended.
@@ -49,22 +57,26 @@ class KX_Scene:
 	@type activity_culling: boolean
 	@ivar activity_culling_radius: The distance outside which to do activity culling.  Measured in manhattan distance.
 	@type activity_culling_radius: float
+	@group Deprecated: getLightList, getObjectList, getName
 	"""
 	
 	def getLightList():
 		"""
+		DEPRECATED: use the 'lights' property.
 		Returns the list of lights in the scene.
 		
 		@rtype: list [L{KX_LightObject}]
 		"""
 	def getObjectList():
 		"""
+		DEPRECATED: use the 'objects' property.
 		Returns the list of objects in the scene.
 		
 		@rtype: list [L{KX_GameObject}]
 		"""
 	def getName():
 		"""
+		DEPRECATED: use the 'name' property.
 		Returns the name of the scene.
 		
 		@rtype: string
diff --git a/source/gameengine/PyDoc/KX_VehicleWrapper.py b/source/gameengine/PyDoc/KX_VehicleWrapper.py
index 087aa167475..3d91b7db676 100644
--- a/source/gameengine/PyDoc/KX_VehicleWrapper.py
+++ b/source/gameengine/PyDoc/KX_VehicleWrapper.py
@@ -1,4 +1,6 @@
-class KX_VehicleWrapper: # (PyObjectPlus)
+from PyObjectPlus import *
+
+class KX_VehicleWrapper(PyObjectPlus):
 	"""
 	KX_VehicleWrapper
 	
diff --git a/source/gameengine/PyDoc/KX_VertexProxy.py b/source/gameengine/PyDoc/KX_VertexProxy.py
index 7ee5087b316..114e0d88075 100644
--- a/source/gameengine/PyDoc/KX_VertexProxy.py
+++ b/source/gameengine/PyDoc/KX_VertexProxy.py
@@ -1,7 +1,9 @@
 # $Id$
 # Documentation for the vertex proxy class
 
-class KX_VertexProxy:
+from SCA_IObject import *
+
+class KX_VertexProxy(SCA_IObject):
 	"""
 	A vertex holds position, UV, colour and normal information.
 	
diff --git a/source/gameengine/PyDoc/PyObjectPlus.py b/source/gameengine/PyDoc/PyObjectPlus.py
new file mode 100644
index 00000000000..1750bcb6ca1
--- /dev/null
+++ b/source/gameengine/PyDoc/PyObjectPlus.py
@@ -0,0 +1,26 @@
+#
+# Documentation for PyObjectPlus base class
+
+class PyObjectPlus:
+	"""
+	PyObjectPlus base class of most other types in the Game Engine.
+	
+	@ivar invalid:	Test if the object has been freed by the game engine and is no longer valid.
+					
+					Normally this is not a problem but when storing game engine data in the GameLogic module,
+					KX_Scenes or other KX_GameObjects its possible to hold a reference to invalid data.
+					Calling an attribute or method on an invalid object will raise a SystemError.
+					
+					The invalid attribute allows testing for this case without exception handling.
+	@type invalid:	bool
+	"""
+	
+	def isA(game_type):
+		"""
+		Check if this is a type or a subtype game_type.
+
+		@param game_type: the name of the type or the type its self from the L{GameTypes} module.
+		@type game_type: string or type
+		@return: True if this object is a type or a subtype of game_type.
+		@rtype: bool
+		"""
diff --git a/source/gameengine/PyDoc/SCA_ILogicBrick.py b/source/gameengine/PyDoc/SCA_ILogicBrick.py
index 4688ba12bb6..2bfe407204a 100644
--- a/source/gameengine/PyDoc/SCA_ILogicBrick.py
+++ b/source/gameengine/PyDoc/SCA_ILogicBrick.py
@@ -1,8 +1,9 @@
 # $Id$
 # Documentation for the logic brick base class SCA_ILogicBrick
 from KX_GameObject import *
+from CValue import *
 
-class SCA_ILogicBrick:
+class SCA_ILogicBrick(CValue):
 	"""
 	Base class for all logic bricks.
 	
@@ -10,6 +11,7 @@ class SCA_ILogicBrick:
 	@type executePriority: int
 	@ivar owner: The game object this logic brick is attached to (read only).
 	@type owner: L{KX_GameObject<KX_GameObject.KX_GameObject>} or None in exceptional cases.
+	@group Deprecated: getOwner, setExecutePriority, getExecutePriority
 	"""
 	
 	def getOwner():
diff --git a/source/gameengine/PyDoc/SCA_IObject.py b/source/gameengine/PyDoc/SCA_IObject.py
new file mode 100644
index 00000000000..92e4884e815
--- /dev/null
+++ b/source/gameengine/PyDoc/SCA_IObject.py
@@ -0,0 +1,9 @@
+# 
+# Documentation for SCA_IObject class
+
+from CValue import *
+class SCA_IObject(CValue):
+	"""
+	This class has no python functions
+	"""
+	pass
diff --git a/source/gameengine/PyDoc/SCA_ISensor.py b/source/gameengine/PyDoc/SCA_ISensor.py
index ab35996aa50..0b72548b103 100644
--- a/source/gameengine/PyDoc/SCA_ISensor.py
+++ b/source/gameengine/PyDoc/SCA_ISensor.py
@@ -24,6 +24,7 @@ class SCA_ISensor(SCA_ILogicBrick):
 	@type triggered: boolean
 	@ivar positive: True if this sensor brick is in a positive state. (Read only)
 	@type positive: boolean
+	@group Deprecated: isPositive, isTriggered, getUsePosPulseMode, setUsePosPulseMode, getFrequency, setFrequency, getUseNegPulseMode,	setUseNegPulseMode, getInvert, setInvert, getLevel, setLevel
 	"""
 	
 	def reset():