diff --git a/source/gameengine/Ketsji/KX_SCA_AddObjectActuator.cpp b/source/gameengine/Ketsji/KX_SCA_AddObjectActuator.cpp index 68b704f4889..7c4f60a7f0a 100644 --- a/source/gameengine/Ketsji/KX_SCA_AddObjectActuator.cpp +++ b/source/gameengine/Ketsji/KX_SCA_AddObjectActuator.cpp @@ -38,7 +38,7 @@ #include "SCA_IScene.h" #include "KX_GameObject.h" #include "KX_IPhysicsController.h" - +#include "blendef.h" #include "PyObjectPlus.h" #ifdef HAVE_CONFIG_H @@ -53,9 +53,9 @@ KX_SCA_AddObjectActuator::KX_SCA_AddObjectActuator(SCA_IObject *gameobj, SCA_IObject *original, int time, SCA_IScene* scene, - const MT_Vector3& linvel, + const float *linvel, bool linv_local, - const MT_Vector3& angvel, + const float *angvel, bool angv_local, PyTypeObject* T) : @@ -63,12 +63,16 @@ KX_SCA_AddObjectActuator::KX_SCA_AddObjectActuator(SCA_IObject *gameobj, m_OriginalObject(original), m_scene(scene), - m_linear_velocity(linvel), m_localLinvFlag(linv_local), - - m_angular_velocity(angvel), m_localAngvFlag(angv_local) { + m_linear_velocity[0] = linvel[0]; + m_linear_velocity[1] = linvel[1]; + m_linear_velocity[2] = linvel[2]; + m_angular_velocity[0] = angvel[0]; + m_angular_velocity[1] = angvel[1]; + m_angular_velocity[2] = angvel[2]; + if (m_OriginalObject) m_OriginalObject->RegisterActuator(this); @@ -188,6 +192,7 @@ PyParentObject KX_SCA_AddObjectActuator::Parents[] = { NULL }; PyMethodDef KX_SCA_AddObjectActuator::Methods[] = { + // ---> deprecated {"setTime", (PyCFunction) KX_SCA_AddObjectActuator::sPySetTime, METH_O, (PY_METHODCHAR)SetTime_doc}, {"getTime", (PyCFunction) KX_SCA_AddObjectActuator::sPyGetTime, METH_NOARGS, (PY_METHODCHAR)GetTime_doc}, {"getLinearVelocity", (PyCFunction) KX_SCA_AddObjectActuator::sPyGetLinearVelocity, METH_NOARGS, (PY_METHODCHAR)GetLinearVelocity_doc}, @@ -196,8 +201,6 @@ PyMethodDef KX_SCA_AddObjectActuator::Methods[] = { {"setAngularVelocity", (PyCFunction) KX_SCA_AddObjectActuator::sPySetAngularVelocity, METH_VARARGS, (PY_METHODCHAR)SetAngularVelocity_doc}, {"getLastCreatedObject", (PyCFunction) KX_SCA_AddObjectActuator::sPyGetLastCreatedObject, METH_NOARGS,"getLastCreatedObject() : get the object handle to the last created object\n"}, {"instantAddObject", (PyCFunction) KX_SCA_AddObjectActuator::sPyInstantAddObject, METH_NOARGS,"instantAddObject() : immediately add object without delay\n"}, - - // ---> deprecated {"setObject", (PyCFunction) KX_SCA_AddObjectActuator::sPySetObject, METH_O, (PY_METHODCHAR)SetObject_doc}, {"getObject", (PyCFunction) KX_SCA_AddObjectActuator::sPyGetObject, METH_VARARGS, (PY_METHODCHAR)GetObject_doc}, @@ -205,41 +208,65 @@ PyMethodDef KX_SCA_AddObjectActuator::Methods[] = { }; PyAttributeDef KX_SCA_AddObjectActuator::Attributes[] = { + KX_PYATTRIBUTE_RW_FUNCTION("object",KX_SCA_AddObjectActuator,pyattr_get_object,pyattr_set_object), + KX_PYATTRIBUTE_RO_FUNCTION("objectLastCreated",KX_SCA_AddObjectActuator,pyattr_get_objectLastCreated), + KX_PYATTRIBUTE_INT_RW("time",0,2000,true,KX_SCA_AddObjectActuator,m_timeProp), + KX_PYATTRIBUTE_FLOAT_ARRAY_RW("linearVelocity",-MAXFLOAT,MAXFLOAT,KX_SCA_AddObjectActuator,m_linear_velocity,3), + KX_PYATTRIBUTE_FLOAT_ARRAY_RW("angularVelocity",-MAXFLOAT,MAXFLOAT,KX_SCA_AddObjectActuator,m_angular_velocity,3), { NULL } //Sentinel }; -PyObject* KX_SCA_AddObjectActuator::_getattr(const char *attr) +PyObject* KX_SCA_AddObjectActuator::pyattr_get_object(void *self, const struct KX_PYATTRIBUTE_DEF *attrdef) { - if (!strcmp(attr, "object")) { - if (!m_OriginalObject) Py_RETURN_NONE; - else return m_OriginalObject->AddRef(); - } else if (!strcmp(attr, "objectLastCreated")) { - if (!m_OriginalObject) Py_RETURN_NONE; - else return m_lastCreatedObject->AddRef(); - } - - _getattr_up(SCA_IActuator); + KX_SCA_AddObjectActuator* actuator = static_cast(self); + if (!actuator->m_OriginalObject) + Py_RETURN_NONE; + else + return actuator->m_OriginalObject->AddRef(); } -int KX_SCA_AddObjectActuator::_setattr(const char *attr, PyObject* value) { - - if (!strcmp(attr, "object")) { - KX_GameObject *gameobj; +int KX_SCA_AddObjectActuator::pyattr_set_object(void *self, const struct KX_PYATTRIBUTE_DEF *attrdef, PyObject *value) +{ + KX_SCA_AddObjectActuator* actuator = static_cast(self); + KX_GameObject *gameobj; - if (!ConvertPythonToGameObject(value, &gameobj, true)) - return 1; // ConvertPythonToGameObject sets the error + if (!ConvertPythonToGameObject(value, &gameobj, true)) + return 1; // ConvertPythonToGameObject sets the error - if (m_OriginalObject != NULL) - m_OriginalObject->UnregisterActuator(this); + if (actuator->m_OriginalObject != NULL) + actuator->m_OriginalObject->UnregisterActuator(actuator); - m_OriginalObject = (SCA_IObject*)gameobj; + actuator->m_OriginalObject = (SCA_IObject*)gameobj; - if (m_OriginalObject) - m_OriginalObject->RegisterActuator(this); + if (actuator->m_OriginalObject) + actuator->m_OriginalObject->RegisterActuator(actuator); - return 0; - } - + return 0; +} + +PyObject* KX_SCA_AddObjectActuator::pyattr_get_objectLastCreated(void *self, const struct KX_PYATTRIBUTE_DEF *attrdef) +{ + KX_SCA_AddObjectActuator* actuator = static_cast(self); + if (!actuator->m_lastCreatedObject) + Py_RETURN_NONE; + else + return actuator->m_lastCreatedObject->AddRef(); +} + + +PyObject* KX_SCA_AddObjectActuator::_getattr(const char *attr) +{ + PyObject* object = _getattr_self(Attributes, this, attr); + if (object != NULL) + return object; + _getattr_up(SCA_IActuator); +} + +int KX_SCA_AddObjectActuator::_setattr(const char *attr, PyObject* value) +{ + int ret = _setattr_self(Attributes, this, attr, value); + if (ret >= 0) + return ret; return SCA_IActuator::_setattr(attr, value); } @@ -280,6 +307,7 @@ const char KX_SCA_AddObjectActuator::SetTime_doc[] = PyObject* KX_SCA_AddObjectActuator::PySetTime(PyObject* self, PyObject* value) { + ShowDeprecationWarning("setTime()", "the time property"); int deltatime = PyInt_AsLong(value); if (deltatime==-1 && PyErr_Occurred()) { PyErr_SetString(PyExc_TypeError, "expected an int"); @@ -296,12 +324,13 @@ PyObject* KX_SCA_AddObjectActuator::PySetTime(PyObject* self, PyObject* value) /* 3. getTime */ const char KX_SCA_AddObjectActuator::GetTime_doc[] = -"GetTime()\n" +"getTime()\n" "\tReturns the lifetime of the object that will be added.\n"; PyObject* KX_SCA_AddObjectActuator::PyGetTime(PyObject* self) { + ShowDeprecationWarning("getTime()", "the time property"); return PyInt_FromLong(m_timeProp); } @@ -339,6 +368,7 @@ const char KX_SCA_AddObjectActuator::GetLinearVelocity_doc[] = PyObject* KX_SCA_AddObjectActuator::PyGetLinearVelocity(PyObject* self) { + ShowDeprecationWarning("getLinearVelocity()", "the linearVelocity property"); PyObject *retVal = PyList_New(3); PyList_SET_ITEM(retVal, 0, PyFloat_FromDouble(m_linear_velocity[0])); @@ -361,12 +391,15 @@ const char KX_SCA_AddObjectActuator::SetLinearVelocity_doc[] = PyObject* KX_SCA_AddObjectActuator::PySetLinearVelocity(PyObject* self, PyObject* args) { + ShowDeprecationWarning("setLinearVelocity()", "the linearVelocity property"); float vecArg[3]; if (!PyArg_ParseTuple(args, "fff", &vecArg[0], &vecArg[1], &vecArg[2])) return NULL; - m_linear_velocity.setValue(vecArg); + m_linear_velocity[0] = vecArg[0]; + m_linear_velocity[1] = vecArg[1]; + m_linear_velocity[2] = vecArg[2]; Py_RETURN_NONE; } @@ -378,6 +411,7 @@ const char KX_SCA_AddObjectActuator::GetAngularVelocity_doc[] = PyObject* KX_SCA_AddObjectActuator::PyGetAngularVelocity(PyObject* self) { + ShowDeprecationWarning("getAngularVelocity()", "the angularVelocity property"); PyObject *retVal = PyList_New(3); PyList_SET_ITEM(retVal, 0, PyFloat_FromDouble(m_angular_velocity[0])); @@ -400,12 +434,15 @@ const char KX_SCA_AddObjectActuator::SetAngularVelocity_doc[] = PyObject* KX_SCA_AddObjectActuator::PySetAngularVelocity(PyObject* self, PyObject* args) { + ShowDeprecationWarning("setAngularVelocity()", "the angularVelocity property"); float vecArg[3]; if (!PyArg_ParseTuple(args, "fff", &vecArg[0], &vecArg[1], &vecArg[2])) return NULL; - m_angular_velocity.setValue(vecArg); + m_angular_velocity[0] = vecArg[0]; + m_angular_velocity[1] = vecArg[1]; + m_angular_velocity[2] = vecArg[2]; Py_RETURN_NONE; } @@ -417,7 +454,7 @@ void KX_SCA_AddObjectActuator::InstantAddObject() // Now it needs to be added to the current scene. SCA_IObject* replica = m_scene->AddReplicaObject(m_OriginalObject,GetParent(),m_timeProp ); KX_GameObject * game_obj = static_cast(replica); - game_obj->setLinearVelocity(m_linear_velocity,m_localLinvFlag); + game_obj->setLinearVelocity(m_linear_velocity ,m_localLinvFlag); game_obj->setAngularVelocity(m_angular_velocity,m_localAngvFlag); game_obj->ResolveCombinedVelocities(m_linear_velocity, m_angular_velocity, m_localLinvFlag, m_localAngvFlag); @@ -453,6 +490,7 @@ const char KX_SCA_AddObjectActuator::GetLastCreatedObject_doc[] = PyObject* KX_SCA_AddObjectActuator::PyGetLastCreatedObject(PyObject* self) { + ShowDeprecationWarning("getLastCreatedObject()", "the objectLastCreated property"); SCA_IObject* result = this->GetLastCreatedObject(); // if result->GetSGNode() is NULL diff --git a/source/gameengine/Ketsji/KX_SCA_AddObjectActuator.h b/source/gameengine/Ketsji/KX_SCA_AddObjectActuator.h index 18298cbcb0c..c8cc7113347 100644 --- a/source/gameengine/Ketsji/KX_SCA_AddObjectActuator.h +++ b/source/gameengine/Ketsji/KX_SCA_AddObjectActuator.h @@ -59,12 +59,12 @@ class KX_SCA_AddObjectActuator : public SCA_IActuator SCA_IScene* m_scene; /// Linear velocity upon creation of the object. - MT_Vector3 m_linear_velocity; + float m_linear_velocity[3]; /// Apply the velocity locally bool m_localLinvFlag; /// Angular velocity upon creation of the object. - MT_Vector3 m_angular_velocity; + float m_angular_velocity[3]; /// Apply the velocity locally bool m_localAngvFlag; @@ -85,9 +85,9 @@ public: SCA_IObject *original, int time, SCA_IScene* scene, - const MT_Vector3& linvel, + const float *linvel, bool linv_local, - const MT_Vector3& angvel, + const float *angvel, bool angv_local, PyTypeObject* T=&Type ); @@ -140,6 +140,9 @@ public: /* 10. instantAddObject*/ KX_PYMETHOD_DOC_NOARGS(KX_SCA_AddObjectActuator,InstantAddObject); + static PyObject* pyattr_get_object(void *self, const struct KX_PYATTRIBUTE_DEF *attrdef); + static int pyattr_set_object(void *self, const struct KX_PYATTRIBUTE_DEF *attrdef, PyObject *value); + static PyObject* pyattr_get_objectLastCreated(void *self, const struct KX_PYATTRIBUTE_DEF *attrdef); }; /* end of class KX_SCA_AddObjectActuator : public KX_EditObjectActuator */ diff --git a/source/gameengine/Ketsji/KX_SceneActuator.cpp b/source/gameengine/Ketsji/KX_SceneActuator.cpp index 1cad4e21352..579c53974d5 100644 --- a/source/gameengine/Ketsji/KX_SceneActuator.cpp +++ b/source/gameengine/Ketsji/KX_SceneActuator.cpp @@ -259,24 +259,83 @@ PyParentObject KX_SceneActuator::Parents[] = PyMethodDef KX_SceneActuator::Methods[] = { + //Deprecated functions ------> {"setUseRestart", (PyCFunction) KX_SceneActuator::sPySetUseRestart, METH_VARARGS, (PY_METHODCHAR)SetUseRestart_doc}, {"setScene", (PyCFunction) KX_SceneActuator::sPySetScene, METH_VARARGS, (PY_METHODCHAR)SetScene_doc}, {"setCamera", (PyCFunction) KX_SceneActuator::sPySetCamera, METH_VARARGS, (PY_METHODCHAR)SetCamera_doc}, {"getUseRestart", (PyCFunction) KX_SceneActuator::sPyGetUseRestart, METH_VARARGS, (PY_METHODCHAR)GetUseRestart_doc}, {"getScene", (PyCFunction) KX_SceneActuator::sPyGetScene, METH_VARARGS, (PY_METHODCHAR)GetScene_doc}, {"getCamera", (PyCFunction) KX_SceneActuator::sPyGetCamera, METH_VARARGS, (PY_METHODCHAR)GetCamera_doc}, + //<----- Deprecated {NULL,NULL} //Sentinel }; PyAttributeDef KX_SceneActuator::Attributes[] = { + KX_PYATTRIBUTE_STRING_RW("scene",0,32,true,KX_SceneActuator,m_nextSceneName), + KX_PYATTRIBUTE_RW_FUNCTION("camera",KX_SceneActuator,pyattr_get_camera,pyattr_set_camera), { NULL } //Sentinel }; PyObject* KX_SceneActuator::_getattr(const char *attr) { + PyObject* object = _getattr_self(Attributes, this, attr); + if (object != NULL) + return object; _getattr_up(SCA_IActuator); } +int KX_SceneActuator::_setattr(const char *attr, PyObject *value) +{ + int ret = _setattr_self(Attributes, this, attr, value); + if (ret >= 0) + return ret; + return SCA_IActuator::_setattr(attr, value); +} + +PyObject* KX_SceneActuator::pyattr_get_camera(void *self, const struct KX_PYATTRIBUTE_DEF *attrdef) +{ + KX_SceneActuator* actuator = static_cast(self); + if (!actuator->m_camera) + Py_RETURN_NONE; + actuator->m_camera->AddRef(); + return actuator->m_camera; +} + +int KX_SceneActuator::pyattr_set_camera(void *self, const struct KX_PYATTRIBUTE_DEF *attrdef, PyObject *value) +{ + KX_SceneActuator* actuator = static_cast(self); + KX_Camera *camOb; + + if (PyObject_TypeCheck(value, &KX_Camera::Type)) + { + camOb = static_cast(value); + if (actuator->m_camera) + actuator->m_camera->UnregisterActuator(actuator); + actuator->m_camera = camOb; + if (actuator->m_camera) + actuator->m_camera->RegisterActuator(actuator); + return 0; + } + + if (PyString_Check(value)) + { + char *camName = PyString_AsString(value); + + camOb = actuator->FindCamera(camName); + if (camOb) + { + if (actuator->m_camera) + actuator->m_camera->UnregisterActuator(actuator); + actuator->m_camera = camOb; + actuator->m_camera->RegisterActuator(actuator); + return 0; + } + PyErr_SetString(PyExc_TypeError, "not a valid camera name"); + return 1; + } + PyErr_SetString(PyExc_TypeError, "expected a string or a camera object reference"); + return 1; +} /* 2. setUseRestart--------------------------------------------------------- */ @@ -288,6 +347,7 @@ PyObject* KX_SceneActuator::PySetUseRestart(PyObject* self, PyObject* args, PyObject* kwds) { + ShowDeprecationWarning("setUseRestart()", "(no replacement)"); int boolArg; if (!PyArg_ParseTuple(args, "i", &boolArg)) @@ -310,6 +370,7 @@ PyObject* KX_SceneActuator::PyGetUseRestart(PyObject* self, PyObject* args, PyObject* kwds) { + ShowDeprecationWarning("getUseRestart()", "(no replacement)"); return PyInt_FromLong(!(m_restart == 0)); } @@ -324,6 +385,7 @@ PyObject* KX_SceneActuator::PySetScene(PyObject* self, PyObject* args, PyObject* kwds) { + ShowDeprecationWarning("setScene()", "the scene property"); /* one argument: a scene, ignore the rest */ char *scene_name; @@ -348,6 +410,7 @@ PyObject* KX_SceneActuator::PyGetScene(PyObject* self, PyObject* args, PyObject* kwds) { + ShowDeprecationWarning("getScene()", "the scene property"); return PyString_FromString(m_nextSceneName); } @@ -362,6 +425,7 @@ PyObject* KX_SceneActuator::PySetCamera(PyObject* self, PyObject* args, PyObject* kwds) { + ShowDeprecationWarning("setCamera()", "the camera property"); PyObject *cam; if (PyArg_ParseTuple(args, "O!", &KX_Camera::Type, &cam)) { @@ -403,6 +467,7 @@ PyObject* KX_SceneActuator::PyGetCamera(PyObject* self, PyObject* args, PyObject* kwds) { + ShowDeprecationWarning("getCamera()", "the camera property"); return PyString_FromString(m_camera->GetName()); } /* eof */ diff --git a/source/gameengine/Ketsji/KX_SceneActuator.h b/source/gameengine/Ketsji/KX_SceneActuator.h index af11af955bf..83b0d63bcd2 100644 --- a/source/gameengine/Ketsji/KX_SceneActuator.h +++ b/source/gameengine/Ketsji/KX_SceneActuator.h @@ -93,6 +93,7 @@ class KX_SceneActuator : public SCA_IActuator /* --------------------------------------------------------------------- */ virtual PyObject* _getattr(const char *attr); + virtual int _setattr(const char *attr, PyObject *value); /* 1. set */ /* Removed */ @@ -110,6 +111,9 @@ class KX_SceneActuator : public SCA_IActuator /* 7. getCamera: */ KX_PYMETHOD_DOC(KX_SceneActuator,GetCamera); + static PyObject* pyattr_get_camera(void *self, const struct KX_PYATTRIBUTE_DEF *attrdef); + static int pyattr_set_camera(void *self, const struct KX_PYATTRIBUTE_DEF *attrdef, PyObject *value); + }; /* end of class KXSceneActuator */ #endif diff --git a/source/gameengine/PyDoc/KX_SCA_AddObjectActuator.py b/source/gameengine/PyDoc/KX_SCA_AddObjectActuator.py index 56068fa641a..974ef718ccf 100644 --- a/source/gameengine/PyDoc/KX_SCA_AddObjectActuator.py +++ b/source/gameengine/PyDoc/KX_SCA_AddObjectActuator.py @@ -9,6 +9,12 @@ class KX_SCA_AddObjectActuator(SCA_IActuator): @type object: KX_GameObject or None @ivar objectLastCreated: the last added object from this actuator (read only). @type objectLastCreated: KX_GameObject or None + @ivar time: the lifetime of added objects, in frames. + @type time: integer + @ivar linearVelocity: the initial linear velocity of added objects. + @type linearVelocity: list [vx, vy, vz] + @ivar angularVelocity: the initial angular velocity of added objects. + @type angularVelocity: list [vx, vy, vz] @warning: An Add Object actuator will be ignored if at game start, the linked object doesn't exist (or is empty) or the linked object is in an active layer. @@ -19,6 +25,7 @@ class KX_SCA_AddObjectActuator(SCA_IActuator): """ def setObject(object): """ + DEPRECATED: use the object property Sets the game object to add. A copy of the object will be added to the scene when the actuator is activated. @@ -31,6 +38,7 @@ class KX_SCA_AddObjectActuator(SCA_IActuator): """ def getObject(name_only = 0): """ + DEPRECATED: use the object property Returns the name of the game object to be added. Returns None if no game object has been assigned to be added. @@ -40,6 +48,7 @@ class KX_SCA_AddObjectActuator(SCA_IActuator): """ def setTime(time): """ + DEPRECATED: use the time property Sets the lifetime of added objects, in frames. If time == 0, the object will last forever. @@ -49,12 +58,14 @@ class KX_SCA_AddObjectActuator(SCA_IActuator): """ def getTime(): """ + DEPRECATED: use the time property Returns the lifetime of the added object, in frames. @rtype: integer """ def setLinearVelocity(vx, vy, vz): """ + DEPRECATED: use the linearVelocity property Sets the initial linear velocity of added objects. @type vx: float @@ -66,12 +77,14 @@ class KX_SCA_AddObjectActuator(SCA_IActuator): """ def getLinearVelocity(): """ + DEPRECATED: use the linearVelocity property Returns the initial linear velocity of added objects. @rtype: list [vx, vy, vz] """ def setAngularVelocity(vx, vy, vz): """ + DEPRECATED: use the angularVelocity property Sets the initial angular velocity of added objects. @type vx: float @@ -83,12 +96,14 @@ class KX_SCA_AddObjectActuator(SCA_IActuator): """ def getAngularVelocity(): """ + DEPRECATED: use the angularVelocity property Returns the initial angular velocity of added objects. @rtype: list [vx, vy, vz] """ def getLastCreatedObject(): """ + DEPRECATED: use the objectLastCreated property Returns the last object created by this actuator. @rtype: L{KX_GameObject} diff --git a/source/gameengine/PyDoc/KX_SceneActuator.py b/source/gameengine/PyDoc/KX_SceneActuator.py index cfb40ae072f..c8912783ab7 100644 --- a/source/gameengine/PyDoc/KX_SceneActuator.py +++ b/source/gameengine/PyDoc/KX_SceneActuator.py @@ -12,21 +12,32 @@ class KX_SceneActuator(SCA_IActuator): This will generate a warning in the console: C{ERROR: GameObject I{OBName} has a SceneActuator I{ActuatorName} (SetScene) without scene} + + Properties: + + @ivar scene: the name of the scene to change to/overlay/underlay/remove/suspend/resume + @type scene: string. + @ivar camera: the camera to change to. + When setting the attribute, you can use either a L{KX_Camera} or the name of the camera. + @type camera: L{KX_Camera} on read, string or L{KX_Camera} on write """ def setUseRestart(flag): """ + DEPRECATED Set flag to True to restart the scene. @type flag: boolean """ def setScene(scene): """ + DEPRECATED: use the scene property instead Sets the name of the scene to change to/overlay/underlay/remove/suspend/resume. @type scene: string """ def setCamera(camera): """ + DEPRECATED: use the camera property instead Sets the camera to change to. Camera can be either a L{KX_Camera} or the name of the camera. @@ -35,12 +46,14 @@ class KX_SceneActuator(SCA_IActuator): """ def getUseRestart(): """ + DEPRECATED Returns True if the scene will be restarted. @rtype: boolean """ def getScene(): """ + DEPRECATED: use the scene property instead Returns the name of the scene to change to/overlay/underlay/remove/suspend/resume. Returns an empty string ("") if no scene has been set. @@ -49,6 +62,7 @@ class KX_SceneActuator(SCA_IActuator): """ def getCamera(): """ + DEPRECATED: use the camera property instead Returns the name of the camera to change to. @rtype: string