simbase.h

五行MMORPG引擎系统V1.0

///     - Delete notifications are sent out.
///     - Finally, the object removes itself from the Sim globals, and tells
///       Sim to get rid of any pending events for it.
///
/// If you call deleteObject(), all of the above tasks are performed, in addition
/// to some sanity checking to make sure the object was previously added properly,
/// and isn't in the process of being deleted. After the object is unregistered, it
/// deallocates itself.
///
/// @section simobject_editor Torque Editors
///
/// SimObjects are one of the building blocks for the in-game editors. They
/// provide a basic interface for the editor to be able to list the fields
/// of the object, update them safely and reliably, and inform the object
/// things have changed.
///
/// This interface is implemented in the following areas:
///     - onNameChange() is called when the object is renamed.
///     - onStaticModified() is called whenever a static field is modified.
///     - inspectPreApply() is called before the object's fields are updated,
///                     when changes are being applied.
///     - inspectPostApply() is called after the object's fields are updated.
///     - onEditorEnable() is called whenever an editor is enabled (for instance,
///                     when you hit F11 to bring up the world editor).
///     - onEditorDisable() is called whenever the editor is disabled (for instance,
///                     when you hit F11 again to close the world editor).
///
/// (Note: you can check the variable gEditingMission to see if the mission editor
/// is running; if so, you may want to render special indicators. For instance, the
/// fxFoliageReplicator renders inner and outer radii when the mission editor is
/// runnning.)
///
/// @section simobject_console The Console
///
/// SimObject extends ConsoleObject by allowing you to
/// to set arbitrary dynamic fields on the object, as well as
/// statically defined fields. This is done through two methods,
/// setDataField and getDataField, which deal with the complexities of
/// allowing access to two different types of object fields.
///
/// Static fields take priority over dynamic fields. This is to be
/// expected, as the role of dynamic fields is to allow data to be
/// stored in addition to the predefined fields.
///
/// The fields in a SimObject are like properties (or fields) in a class.
///
/// Some fields may be arrays, which is what the array parameter is for; if it's non-null,
/// then it is parsed with dAtoI and used as an index into the array. If you access something
/// as an array which isn't, then you get an empty string.
///
/// <b>You don't need to read any further than this.</b> Right now,
/// set/getDataField are called a total of 6 times through the entire
/// Torque codebase. Therefore, you probably don't need to be familiar
/// with the details of accessing them. You may want to look at Con::setData
/// instead. Most of the time you will probably be accessing fields directly,
/// or using the scripting language, which in either case means you don't
/// need to do anything special.
///
/// The functions to get/set these fields are very straightforward:
///
/// @code
///  setDataField(StringTable->insert("locked", false), NULL, b ? "true" : "false" );
///  curObject->setDataField(curField, curFieldArray, STR.getStringValue());
///  setDataField(slotName, array, value);
/// @endcode
///
/// <i>For advanced users:</i> There are two flags which control the behavior
/// of these functions. The first is ModStaticFields, which controls whether
/// or not the DataField functions look through the static fields (defined
/// with addField; see ConsoleObject for details) of the class. The second
/// is ModDynamicFields, which controls dynamically defined fields. They are
/// set automatically by the console constructor code.
///
/// @nosubgrouping
class SimObject: public ConsoleObject
{
   typedef ConsoleObject Parent;

   friend class SimManager;
   friend class SimGroup;
   friend class SimNameDictionary;
   friend class SimManagerNameDictionary;
   friend class SimIdDictionary;
//#ifdef TGE_RPG
//   friend class SimObject;
//#endif
   //-------------------------------------- Structures and enumerations
  private:

   /// Flags for use in mFlags
   enum {
      Deleted   = BIT(0),   ///< This object is marked for deletion.
      Removed   = BIT(1),   ///< This object has been unregistered from the object system.
      Added     = BIT(3),   ///< This object has been registered with the object system.
      Selected  = BIT(4),   ///< This object has been marked as selected. (in editor)
      Expanded  = BIT(5),   ///< This object has been marked as expanded. (in editor)
      ModStaticFields  = BIT(6),    ///< The object allows you to read/modify static fields
      ModDynamicFields = BIT(7)     ///< The object allows you to read/modify dynamic fields
   };
  public:
   /// @name Notification
   /// @{
   struct Notify {
      enum Type {
         ClearNotify,   ///< Notified when the object is cleared.
         DeleteNotify,  ///< Notified when the object is deleted.
         ObjectRef,     ///< Cleverness to allow tracking of references.
         Invalid        ///< Mark this notification as unused (used in freeNotify).
      } type;
      void *ptr;        ///< Data (typically referencing or interested object).
      Notify *next;     ///< Next notification in the linked list.
   };

   /// @}

   enum WriteFlags {
      SelectedOnly = BIT(0), ///< Passed to SimObject::write to indicate that only objects
                            ///  marked as selected should be outputted. Used in SimSet.

									 /// TGE_Theme
      ObjectExists = BIT(1)  ///< Passed to SimObject::write to indicate that the object exists
										/// used to write out only selected profiles - EAG Theme Editor   
	};

  private:
   // dictionary information stored on the object
   StringTableEntry objectName;
   SimObject*       nextNameObject;
   SimObject*       nextManagerNameObject;
   SimObject*       nextIdObject;

   SimGroup*   mGroup;  ///< SimGroup we're contained in, if any.
   BitSet32    mFlags;

   /// @name Notification
   /// @{
   Notify*     mNotifyList;
   /// @}

  protected:
   SimObjectId mId;         ///< Id number for this object.
   Namespace*  mNameSpace;
   U32         mTypeMask;

  protected:
   /// @name Notification
   /// Helper functions for notification code.
   /// @{

   static SimObject::Notify *mNotifyFreeList;
   static SimObject::Notify *allocNotify();     ///< Get a free Notify structure.
   static void freeNotify(SimObject::Notify*);  ///< Mark a Notify structure as free.

   /// @}

  private:
   SimFieldDictionary *mFieldDictionary;    ///< Storage for dynamic fields.

  public:
   /// @name Accessors
   /// @{

   /// Get the value of a field on the object.
   ///
   /// See @ref simobject_console "here" for a detailed discussion of what this
   /// function does.
   ///
   /// @param   slotName    Field to access.
   /// @param   array       String containing index into array
   ///                      (if field is an array); if NULL, it is ignored.
   const char *getDataField(StringTableEntry slotName, const char *array);

   /// Set the value of a field on the object.
   ///
   /// See @ref simobject_console "here" for a detailed discussion of what this
   /// function does.
   ///
   /// @param   slotName    Field to access.
   /// @param   array       String containing index into array; if NULL, it is ignored.
   /// @param   value       Value to store.
   void setDataField(StringTableEntry slotName, const char *array, const char *value);

   /// Get reference to the dictionary containing dynamic fields.
   ///
   /// See @ref simobject_console "here" for a detailed discussion of what this
   /// function does.
   ///
   /// This dictionary can be iterated over using a SimFieldDictionaryIterator.
   SimFieldDictionary * getFieldDictionary() {return(mFieldDictionary);}

   /// @}

   /// @name Initialization
   /// @{

   ///
   SimObject();
   virtual ~SimObject();

   virtual bool processArguments(S32 argc, const char **argv);  ///< Process constructor options. (ie, new SimObject(1,2,3))

   /// @}

   /// @name Events
   /// @{
   virtual bool onAdd();                                ///< Called when the object is added to the sim.
   virtual void onRemove();                             ///< Called when the object is removed from the sim.
   virtual void onGroupAdd();                           ///< Called when the object is added to a SimGroup.
   virtual void onGroupRemove();                        ///< Called when the object is removed from a SimGroup.
   virtual void onNameChange(const char *name);         ///< Called when the object's name is changed.
   virtual void onStaticModified(const char* slotName); ///< Called when a static field is modified.
                                                        ///
                                                        ///  Specifically, this is called by setDataField
                                                        ///  when a static field is modified, see
                                                        ///  @ref simobject_console "the console details".

   /// Called before any property of the object is changed in the world editor.
   ///
   /// The calling order here is:
   ///  - inspectPreApply()
   ///  - ...
   ///  - calls to setDataField()
   ///  - ...
   ///  - inspectPostApply()
   virtual void inspectPreApply();

   /// Called after any property of the object is changed in the world editor.
   ///
   /// @see inspectPreApply
   virtual void inspectPostApply();

   /// Called when a SimObject is deleted.
   ///
   /// When you are on the notification list for another object
   /// and it is deleted, this method is called.
   virtual void onDeleteNotify(SimObject *object);

   /// Called when the editor is activated.
   virtual void onEditorEnable(){};

   /// Called when the editor is deactivated.
   virtual void onEditorDisable(){};

   /// @}

   /// Find a named sub-object of this object.
   ///
   /// This is subclassed in the SimGroup and SimSet classes.
   ///
   /// For a single object, it just returns NULL, as normal objects cannot have children.
   virtual SimObject *findObject(const char *name);

   /// @name Notification
   /// @{
   Notify *removeNotify(void *ptr, Notify::Type);   ///< Remove a notification from the list.
   void deleteNotify(SimObject* obj);               ///< Notify an object when we are deleted.
   void clearNotify(SimObject* obj);                ///< Notify an object when we are cleared.
   void clearAllNotifications();                    ///< Remove all notifications for this object.
   void processDeleteNotifies();                    ///< Send out deletion notifications.

   /// Register a reference to this object.
   ///
   /// You pass a pointer to your reference to this object.
   ///
   /// When the object is deleted, it will null your
   /// pointer, ensuring you don't access old memory.
   ///
   /// @param obj   Pointer to your reference to the object.
   void registerReference(SimObject **obj);

   /// Unregister a reference to this object.
   ///
   /// Remove a reference from the list, so that it won't
   /// get nulled inappropriately.
   ///
   /// Call this when you're done with your reference to
   /// the object, especially if you're going to free the
   /// memory. Otherwise, you may erroneously get something
   /// overwritten.
   ///
   /// @see registerReference
   void unregisterReference(SimObject **obj);

   /// @}

   /// @name Registration
   ///
   /// SimObjects must be registered with the object system.
   /// @{


   /// Register an object with the object system.
   ///
   /// This must be called if you want to keep the object around.
   /// In the rare case that you will delete the object immediately, or
   /// don't want to be able to use Sim::findObject to locate it, then
   /// you don't need to register it.
   ///
   /// registerObject adds the object to the global ID and name dictionaries,
   /// after first assigning it a new ID number. It calls onAdd(). If onAdd fails,
   /// it unregisters the object and returns false.
   ///
   /// If a subclass's onAdd doesn't eventually call SimObject::onAdd(), it will
   /// cause an assertion.
   bool registerObject();

   /// Register the object, forcing the id.
   ///
   /// @see registerObject()
   /// @param   id  ID to assign to the object.
   bool registerObject(U32 id);

   /// Register the object, assigning the name.
   ///
   /// @see registerObject()
   /// @param   name  Name to assign to the object.
   bool registerObject(const char *name);

   /// Register the object, assigning a name and ID.
   ///
   /// @see registerObject()
   /// @param   name  Name to assign to the object.
   /// @param   id  ID to assign to the object.
   bool registerObject(const char *name, U32 id);

   /// Unregister the object from Sim.
   ///
   /// This performs several operations:
   ///  - Sets the removed flag.
   ///  - Call onRemove()
   ///  - Clear out notifications.
   ///  - Remove the object from...
   ///      - its group, if any. (via getGroup)
   ///      - Sim::gNameDictionary
   ///      - Sim::gIDDictionary
   ///  - Finally, cancel any pending events for this object (as it can't receive them now).
   void unregisterObject();

   void deleteObject();     ///< Unregister, mark as deleted, and free the object.
                            ///
                            /// This helper function can be used when you're done with the object
                            /// and don't want to be bothered with the details of cleaning it up.

   /// @}

   /// @name Accessors
   /// @{
   SimObjectId getId() const { return mId; }
   const char* getIdString();
   U32         getType() const  { return mTypeMask; }
   const char* getName() const { return objectName; };

   void setId(SimObjectId id);
   void assignName(const char* name);
#ifdef TGE_RPG
   void assignSoleName(const char* name);
#endif
   SimGroup* getGroup() const { return mGroup; }
   bool isProperlyAdded() const { return mFlags.test(Added); }
   bool isDeleted() const { return mFlags.test(Deleted); }