 | PixelLight 0.9.11-R1 Copyright (C) 2002-2012 by The PixelLight Team Last modified Thu Feb 23 2012 14:08:57 |  | The content of this PixelLight
document is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported |
|
PixelLightAPI
.
|
00001 /*********************************************************\ 00002 * File: Object.h * 00003 * 00004 * Copyright (C) 2002-2012 The PixelLight Team (http://www.pixellight.org/) 00005 * 00006 * This file is part of PixelLight. 00007 * 00008 * PixelLight is free software: you can redistribute it and/or modify 00009 * it under the terms of the GNU Lesser General Public License as published by 00010 * the Free Software Foundation, either version 3 of the License, or 00011 * (at your option) any later version. 00012 * 00013 * PixelLight is distributed in the hope that it will be useful, 00014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00016 * GNU Lesser General Public License for more details. 00017 * 00018 * You should have received a copy of the GNU Lesser General Public License 00019 * along with PixelLight. If not, see <http://www.gnu.org/licenses/>. 00020 \*********************************************************/ 00021 00022 00023 #ifndef __PLCORE_OBJECT_H__ 00024 #define __PLCORE_OBJECT_H__ 00025 #pragma once 00026 00027 00028 //[-------------------------------------------------------] 00029 //[ Includes ] 00030 //[-------------------------------------------------------] 00031 #include "PLCore/PLCoreDefinitions.h" 00032 #include "PLCore/Xml/XmlElement.h" 00033 #include "PLCore/Container/List.h" 00034 #include "PLCore/Base/Rtti.h" 00035 00036 00037 //[-------------------------------------------------------] 00038 //[ Namespace ] 00039 //[-------------------------------------------------------] 00040 namespace PLCore { 00041 00042 00043 //[-------------------------------------------------------] 00044 //[ Forward declarations ] 00045 //[-------------------------------------------------------] 00046 class Class; 00047 class DynVar; 00048 class DynEvent; 00049 class DynEventHandler; 00050 class DynConstructor; 00051 class DynParams; 00052 00053 00054 //[-------------------------------------------------------] 00055 //[ Classes ] 00056 //[-------------------------------------------------------] 00057 /** 00058 * @brief 00059 * Internal Object base class 00060 * 00061 * @note 00062 * - Initially the reference counter is 1 (Lookout! Within the "RefCount"-template it's 0) 00063 */ 00064 class ObjectBase { 00065 00066 00067 //[-------------------------------------------------------] 00068 //[ RTTI interface ] 00069 //[-------------------------------------------------------] 00070 public: 00071 // Properties 00072 pl_properties 00073 pl_properties_end 00074 00075 00076 //[-------------------------------------------------------] 00077 //[ Public functions ] 00078 //[-------------------------------------------------------] 00079 public: 00080 /** 00081 * @brief 00082 * Constructor 00083 */ 00084 PLCORE_API ObjectBase(); 00085 00086 /** 00087 * @brief 00088 * Destructor 00089 */ 00090 PLCORE_API virtual ~ObjectBase(); 00091 00092 /** 00093 * @brief 00094 * Get class 00095 * 00096 * @return 00097 * Class of the object (do not destroy the returned instance, should never be a null pointer, unless something is *terribly* wrong ;-) ) 00098 */ 00099 PLCORE_API virtual Class *GetClass() const; 00100 00101 //[-------------------------------------------------------] 00102 //[ Reference counting ("RefCount"-template interface) ] 00103 //[-------------------------------------------------------] 00104 /** 00105 * @brief 00106 * Get a pointer to the object 00107 * 00108 * @return 00109 * Pointer to the reference counter's object, NEVER a null pointer! 00110 */ 00111 PLCORE_API const ObjectBase *GetPointer() const; 00112 PLCORE_API ObjectBase *GetPointer(); 00113 00114 /** 00115 * @brief 00116 * Increases the reference count 00117 * 00118 * @return 00119 * Current reference count 00120 */ 00121 PLCORE_API uint32 AddReference(); 00122 00123 /** 00124 * @brief 00125 * Decreases the reference count 00126 * 00127 * @return 00128 * Current reference count 00129 * 00130 * @note 00131 * - When the last reference was released, the instance is destroyed automatically 00132 */ 00133 PLCORE_API uint32 Release(); 00134 00135 /** 00136 * @brief 00137 * Gets the current reference count 00138 * 00139 * @return 00140 * Current reference count 00141 */ 00142 PLCORE_API uint32 GetRefCount() const; 00143 00144 //[-------------------------------------------------------] 00145 //[ Reference counting ] 00146 //[-------------------------------------------------------] 00147 /** 00148 * @brief 00149 * Decreases the reference count without destroying this instance automatically 00150 * 00151 * @return 00152 * Current reference count 00153 * 00154 * @note 00155 * - Whenever possible, do not use this method, use "Release()" instead 00156 * - Unlike "Release()", when the last reference was released the instance is not destroyed automatically 00157 * - Use this method e.g. to release the initial set reference so e.g. a script can have the total control over an instance 00158 */ 00159 PLCORE_API uint32 SoftRelease(); 00160 00161 00162 //[-------------------------------------------------------] 00163 //[ Private data ] 00164 //[-------------------------------------------------------] 00165 private: 00166 uint32 m_nRefCount; /**< Reference count */ 00167 00168 00169 }; 00170 00171 00172 /** 00173 * @brief 00174 * Object base class 00175 */ 00176 class Object : public ObjectBase { 00177 00178 00179 //[-------------------------------------------------------] 00180 //[ RTTI interface ] 00181 //[-------------------------------------------------------] 00182 pl_class_internal(PLCORE_RTTI_EXPORT, Object, "PLCore", /* No base class */, "Object base class") 00183 #ifdef PLCORE_EXPORTS // The following is only required when compiling PLCore 00184 // Methods 00185 pl_method_1(IsInstanceOf, pl_ret_type(bool), const String&, "Check if object is instance of a given class. Class name (with namespace) as first parameter. Returns 'true' if the object is an instance of the class or one of it's derived classes, else 'false'.", "") 00186 pl_method_2(SetAttribute, pl_ret_type(void), const String&, const String&, "Set attribute value. Attribute name as first parameter, attribute value as second parameter.", "") 00187 pl_method_1(SetAttributeDefault, pl_ret_type(void), const String&, "Set attribute to it's default value. Attribute name as first parameter.", "") 00188 pl_method_2(CallMethod, pl_ret_type(void), const String&, const String&, "Call method. Method name as first parameter, parameters as string (e.g. \"Param0='x' Param1='y'\") as second parameter.", "") 00189 pl_method_1(SetValues, pl_ret_type(void), const String&, "Set multiple attribute values as a string at once. String containing attributes and values as first parameter (e.g. \"Name='Bob' Position='1 2 3'\").", "") 00190 pl_method_0(SetDefaultValues, pl_ret_type(void), "Set all attributes to default.", "") 00191 pl_method_0(ToString, pl_ret_type(String), "Get the object as string. Returns string representation of object.", "") 00192 pl_method_1(FromString, pl_ret_type(void), const String&, "Set the object from string. String representation of object as first parameter.", "") 00193 #endif 00194 // Signals 00195 pl_signal_0(SignalDestroyed, "Object destroyed signal. When this signal is emitted the object is already in the destruction phase and parts may already be invalid. Best to e.g. only update our object pointer.", "") 00196 pl_class_end 00197 00198 00199 //[-------------------------------------------------------] 00200 //[ Public functions ] 00201 //[-------------------------------------------------------] 00202 public: 00203 /** 00204 * @brief 00205 * Constructor 00206 */ 00207 PLCORE_API Object(); 00208 00209 /** 00210 * @brief 00211 * Destructor 00212 */ 00213 PLCORE_API virtual ~Object(); 00214 00215 //[-------------------------------------------------------] 00216 //[ Class and members ] 00217 //[-------------------------------------------------------] 00218 /** 00219 * @brief 00220 * Check if object is instance of a given class by using a given class reference 00221 * 00222 * @param[in] cClass 00223 * Class 00224 * 00225 * @return 00226 * 'true' if the object is an instance of the class or one of it's derived classes, else 'false' 00227 */ 00228 PLCORE_API bool IsInstanceOfByReference(const Class &cClass) const; 00229 00230 /** 00231 * @brief 00232 * Check if object is instance of a given class 00233 * 00234 * @param[in] sClass 00235 * Class name (with namespace) 00236 * 00237 * @return 00238 * 'true' if the object is an instance of the class or one of it's derived classes, else 'false' 00239 */ 00240 PLCORE_API bool IsInstanceOf(const String &sClass) const; 00241 00242 /** 00243 * @brief 00244 * Get attributes 00245 * 00246 * @return 00247 * List of attributes (do not destroy the returned attribute instances) 00248 * 00249 * @remarks 00250 * Use this function with caution, as the list is assembled and copied each time the function is called! 00251 * In general it is recommended to use GetClass()->GetAttributes() to obtain a list of attribute descriptors 00252 * and then call GetAttribute() from the descriptor to get access to the actual attribute 00253 */ 00254 PLCORE_API const List<DynVar*> GetAttributes() const; 00255 00256 /** 00257 * @brief 00258 * Get attribute 00259 * 00260 * @param[in] sName 00261 * Attribute name 00262 * 00263 * @return 00264 * Attribute (do not destroy the returned instance, can be a null pointer, if no attribute with that name could be found) 00265 */ 00266 PLCORE_API DynVar *GetAttribute(const String &sName) const; 00267 00268 /** 00269 * @brief 00270 * Get all callable methods 00271 * 00272 * @param[out] lstMethods 00273 * Receives the list of callable methods, the given list is not cleared before new entries are added (do not destroy the returned instances) 00274 * 00275 * @remarks 00276 * Performance warning: Use this function with caution, as the list is assembled and callable method 00277 * instances are created each time the function is called! 00278 * If you only need the method descriptors, use GetClass()->GetMethods() instead. 00279 */ 00280 PLCORE_API void GetMethods(List<DynFuncPtr> &lstMethods); 00281 00282 /** 00283 * @brief 00284 * Get callable method by using a given method name 00285 * 00286 * @param[in] sName 00287 * Method name 00288 * 00289 * @return 00290 * Callable method (do not destroy the returned instance, can be a null pointer, if no method with that name could be found) 00291 * 00292 * @remarks 00293 * Performance warning: Use this function with caution, as the callable method instance is 00294 * created each time the function is called! 00295 * If you only need the method descriptor, use GetClass()->GetMethod() instead. 00296 */ 00297 PLCORE_API DynFuncPtr GetMethod(const String &sName); 00298 00299 /** 00300 * @brief 00301 * Get a list of all signals 00302 * 00303 * @return 00304 * List of signals (do not destroy the returned instances) 00305 * 00306 * @remarks 00307 * Use this function with caution, as the list is assembled and copied each time the function is called! 00308 * In general it is recommended to use GetClass()->GetSignals() to obtain a list of signal descriptors 00309 * and then call GetSignal() from the descriptor to get access to the actual signal 00310 */ 00311 PLCORE_API const List<DynEvent*> GetSignals() const; 00312 00313 /** 00314 * @brief 00315 * Get signal by using a given signal name 00316 * 00317 * @param[in] sName 00318 * Signal name 00319 * 00320 * @return 00321 * Signal (do not destroy the returned instance, can be a null pointer, if no signal with that name could be found) 00322 */ 00323 PLCORE_API DynEvent *GetSignal(const String &sName) const; 00324 00325 /** 00326 * @brief 00327 * Get a list of all slots 00328 * 00329 * @return 00330 * List of slots (do not destroy the returned instances) 00331 * 00332 * @remarks 00333 * Use this function with caution, as the list is assembled and copied each time the function is called! 00334 * In general it is recommended to use GetClass()->GetSlots() to obtain a list of slot descriptors 00335 * and then call GetSlot() from the descriptor to get access to the actual slot 00336 */ 00337 PLCORE_API const List<DynEventHandler*> GetSlots() const; 00338 00339 /** 00340 * @brief 00341 * Get slot by using a given slot name 00342 * 00343 * @param[in] sName 00344 * Slot name 00345 * 00346 * @return 00347 * Slot (do not destroy the returned instance, can be a null pointer, if no slot with that name could be found) 00348 */ 00349 PLCORE_API DynEventHandler *GetSlot(const String &sName) const; 00350 00351 //[-------------------------------------------------------] 00352 //[ Direct access functions ] 00353 //[-------------------------------------------------------] 00354 /** 00355 * @brief 00356 * Set attribute value by using a given string value 00357 * 00358 * @param[in] sName 00359 * Attribute name 00360 * @param[in] sValue 00361 * Attribute value as string 00362 */ 00363 PLCORE_API void SetAttribute(const String &sName, const String &sValue); 00364 00365 /** 00366 * @brief 00367 * Set attribute value by using a given dynamic variable reference 00368 * 00369 * @param[in] sName 00370 * Attribute name 00371 * @param[in] cVar 00372 * Attribute value as dynamic variable reference 00373 */ 00374 PLCORE_API void SetAttribute(const String &sName, const DynVar &cVar); 00375 00376 /** 00377 * @brief 00378 * Set attribute value by using a given dynamic variable pointer 00379 * 00380 * @param[in] sName 00381 * Attribute name 00382 * @param[in] pVar 00383 * Attribute value as dynamic variable pointer, in case of a null pointer, nothing happens at all 00384 * 00385 * @remarks 00386 * This is a comfort method allowing to write e.g. 00387 * pFirstObject->SetAttribute("MyAttribute", pSecondObject->GetAttribute("MyAttribute")); 00388 * instead of 00389 * DynVar *pDynVar = pSecondObject->GetAttribute(); 00390 * if (pDynVar) 00391 * pFirstObject->SetAttribute("MyAttribute", *pDynVar); 00392 * In case there's no such attribute in "pSecondObject", nothing happens at all. 00393 */ 00394 PLCORE_API void SetAttribute(const String &sName, const DynVar *pVar); 00395 00396 /** 00397 * @brief 00398 * Set attribute to it's default value 00399 * 00400 * @param[in] sName 00401 * Attribute name 00402 */ 00403 PLCORE_API void SetAttributeDefault(const String &sName); 00404 00405 /** 00406 * @brief 00407 * Call method with given dynamic parameters 00408 * 00409 * @param[in] sName 00410 * Method name 00411 * @param[in] cParams 00412 * Dynamic parameters 00413 */ 00414 PLCORE_API void CallMethod(const String &sName, DynParams &cParams); 00415 00416 /** 00417 * @brief 00418 * Call method with given constant dynamic parameters 00419 * 00420 * @param[in] sName 00421 * Method name 00422 * @param[in] cParams 00423 * Constant dynamic parameters 00424 */ 00425 PLCORE_API void CallMethod(const String &sName, const DynParams &cParams); 00426 00427 /** 00428 * @brief 00429 * Call method with parameters given as string 00430 * 00431 * @param[in] sName 00432 * Method name 00433 * @param[in] sParams 00434 * Parameters as string 00435 */ 00436 PLCORE_API void CallMethod(const String &sName, const String &sParams); 00437 00438 /** 00439 * @brief 00440 * Call method with parameters given as XML element 00441 * 00442 * @param[in] sName 00443 * Method name 00444 * @param[in] cElement 00445 * Parameters as XML element 00446 */ 00447 PLCORE_API void CallMethod(const String &sName, const XmlElement &cElement); 00448 00449 //[-------------------------------------------------------] 00450 //[ Object state functions ] 00451 //[-------------------------------------------------------] 00452 /** 00453 * @brief 00454 * Get attribute values as a string 00455 * 00456 * @param[in] nDefaultValue 00457 * 'WithDefault' to retrieve all attributes, 'NoDefault' to only retrieve attributes that are not set to default 00458 * 00459 * @return 00460 * String containing attributes and values 00461 * 00462 * @remarks 00463 * The returned string contains the attributes and their values. 00464 * Example: "Name='Test' IntValue='10'" 00465 */ 00466 PLCORE_API String GetValues(EDefaultValue nDefaultValue = NoDefault) const; 00467 00468 /** 00469 * @brief 00470 * Set multiple attribute values as a string at once 00471 * 00472 * @param[in] sVars 00473 * String containing attributes and values (e.g. \"Name='Bob' Position='1 2 3'\") 00474 */ 00475 PLCORE_API void SetValues(const String &sVars); 00476 00477 /** 00478 * @brief 00479 * Get attribute values as XML 00480 * 00481 * @param[out] cElement 00482 * XML element 00483 * @param[in] nDefaultValue 00484 * 'WithDefault' to retrieve all attributes, 'NoDefault' to only retrieve attributes that are not set to default 00485 * 00486 * @remarks 00487 * The attributes and their values are added as XML-attributes to the given XML-element 00488 */ 00489 PLCORE_API void GetValuesXml(XmlElement &cElement, EDefaultValue nDefaultValue = NoDefault) const; 00490 00491 /** 00492 * @brief 00493 * Set attribute values from XML 00494 * 00495 * @param[out] cElement 00496 * XML element 00497 * 00498 * @remarks 00499 * The attributes and their values are read from the XML-attributes of the given XML-element 00500 */ 00501 PLCORE_API void SetValuesXml(const XmlElement &cElement); 00502 00503 /** 00504 * @brief 00505 * Set all attributes to default 00506 */ 00507 PLCORE_API void SetDefaultValues(); 00508 00509 00510 //[-------------------------------------------------------] 00511 //[ Public virtual Object functions ] 00512 //[-------------------------------------------------------] 00513 public: 00514 /** 00515 * @brief 00516 * Get object as string 00517 * 00518 * @return 00519 * String representation of object 00520 */ 00521 PLCORE_API virtual String ToString() const; 00522 00523 /** 00524 * @brief 00525 * Set object from string 00526 * 00527 * @param[in] sString 00528 * String representation of object 00529 */ 00530 PLCORE_API virtual void FromString(const String &sString); 00531 00532 /** 00533 * @brief 00534 * Get object as XML 00535 * 00536 * @return 00537 * XML representation of object 00538 */ 00539 PLCORE_API virtual XmlElement ToXml() const; 00540 00541 /** 00542 * @brief 00543 * Set object from XML 00544 * 00545 * @param[in] cElement 00546 * XML representation of object 00547 */ 00548 PLCORE_API virtual void FromXml(const XmlElement &cElement); 00549 00550 00551 }; 00552 00553 00554 //[-------------------------------------------------------] 00555 //[ Namespace ] 00556 //[-------------------------------------------------------] 00557 } // PLCore 00558 00559 00560 #endif // __PLCORE_OBJECT_H__
|