xsSerializable Class Reference

Base class encapsulating object which can be serialized/deserialized to/from XML file (disk file or any stream). This class acts as a data container for properties (xsProperty class objects) encapsulating serialized class data members. More...

#include <XmlSerializer.h>

Collaboration diagram for xsSerializable:
Collaboration graph
[legend]

List of all members.

Public Types

enum  SEARCHMODE { searchDFS, searchBFS }

Public Member Functions

 XS_DECLARE_CLONABLE_CLASS (xsSerializable)
 xsSerializable ()
 Constructor.
 xsSerializable (const xsSerializable &obj)
 Copy constructor.
 ~xsSerializable ()
 Destructor.
xsSerializableGetParent ()
 Get serializable parent object.
wxXmlSerializerGetParentManager ()
 Get parent data manager (instance of wxXmlSerializer).
xsSerializableGetFirstChild ()
 Get first serializable child object.
xsSerializableGetFirstChild (wxClassInfo *type)
 Get first serializable child object of given type.
xsSerializableGetLastChild ()
 Get last serializable child object.
xsSerializableGetLastChild (wxClassInfo *type)
 Get last serializable child object of given type.
xsSerializableGetSibbling ()
 Get next serializable sibbling object.
xsSerializableGetSibbling (wxClassInfo *type)
 Get next serializable sibbling object of given type.
xsSerializableGetChild (long id, bool recursive=xsNORECURSIVE)
 Get child item with given ID if exists.
bool HasChildren () const
 Function finds out whether this serializable item has some children.
SerializableList & GetChildrenList ()
 Get list of children (serializable objects) of this object.
void GetChildren (wxClassInfo *type, SerializableList &list)
 Get children of given type.
void GetChildrenRecursively (wxClassInfo *type, SerializableList &list, SEARCHMODE mode=searchBFS)
 Get all children of given type recursively (i.e. children of children of .... ).
SerializableList::compatibility_iterator GetFirstChildNode () const
 Get pointer to list node containing first serializable child object.
SerializableList::compatibility_iterator GetLastChildNode () const
 Get pointer to list node containing last serializable child object.
void SetParent (xsSerializable *parent)
 Set serializable parent object.
void SetParentManager (wxXmlSerializer *parent)
 Set parent data manager.
xsSerializableAddChild (xsSerializable *child)
 Add serializable child object to this object.
xsSerializableInsertChild (size_t pos, xsSerializable *child)
 Insert serializable child object to this object at given position.
void Reparent (xsSerializable *parent)
 Assign this object as a child to given parent object.
void SetId (long id)
 Set ID of this object. Can be used for further objects' handling by wxXmlSerializer class (default ID value is -1). This functions should NOT be used directly; it is called by wxXmlSerializer object in the case that this serializable object is attached to another one (or directly to root node of wxXmlSerializer) by wxXmlSerializer::AddItem() member function.
long GetId () const
 Get object ID.
wxXmlNode * SerializeObject (wxXmlNode *node)
 Create new 'object' XML node and serialize all marked class data members (properties) into it.
void DeserializeObject (wxXmlNode *node)
 Deserialize marked class data members (properties) from appropriate fields of given parent 'object' XML node.
void AddProperty (xsProperty *property)
 Add new property to the property list.
void RemoveProperty (xsProperty *property)
 Remove given property from the property list.
xsPropertyGetProperty (const wxString &field)
 Get serialized property of given name.
PropertyList & GetProperties ()
 Get reference to properties list.
void EnablePropertySerialization (const wxString &field, bool enab)
 Enable/disable serialization of given property.
bool IsPropertySerialized (const wxString &field)
 Returns information whether the given property is serialized or not.
void EnableSerialization (bool enab)
 Enable/disable object serialization.
bool IsSerialized () const
 Returns information whether the object can be serialized or not.
void EnableCloning (bool enab)
 Enable/disable object cloning.
bool IsCloningEnabled () const
 Returns information whether the object can be cloned or not.
xsSerializableoperator<< (xsSerializable *child)
 Add serializable child object to this object.

Protected Member Functions

void InitChild (xsSerializable *child)
 Initialize new child object.
virtual wxXmlNode * Serialize (wxXmlNode *node)
 Serialize stored properties to the given XML node. The serialization routine is automatically called by the framework and cares about serialization of all defined properties.
virtual void Deserialize (wxXmlNode *node)
 Deserialize object properties from the given XML node. The routine is automatically called by the framework and cares about deserialization of all defined properties.

Protected Attributes

PropertyList m_lstProperties
 List of serialized properties.
SerializableList m_lstChildItems
 List of child objects.
xsSerializablem_pParentItem
 Pointer to parent serializable object.
wxXmlSerializerm_pParentManager
 Pointer to parent data manager.
bool m_fSerialize
 Object serialization flag.
bool m_fClone
 Object cloning flag.

Private Attributes

long m_nId
 Object ID.

Friends

class wxXmlSerializer

Detailed Description

Base class encapsulating object which can be serialized/deserialized to/from XML file (disk file or any stream). This class acts as a data container for properties (xsProperty class objects) encapsulating serialized class data members.

Class data members which should be serialized must be marked by appropriate macro defined in wxXmlSerializer.h header file (it is recommended to mark desired data members in the class constructor).

Instances of this class can be arranged into a list/d-ary tree hierarchy so it can behave like powerfull data container. All chained serializable class objects can be handled by class member functions or by member functions of wxXmlSerializer class object which should be used as their manager (recommended way).

Another built-in (optional) functionality is class instaces' cloning. User can use XS_DECLARE_CLONABLE_CLASS and XS_IMPLEMENT_CLONABLE_CLASS macros instead of classic DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS macros which lead to definition of xsSerializable::Clone() virtual function used for cloning of current class instance via its copy constructor (user must define it manually). Virtual xsSerializble::Clone() function is also used by the wxXmlSerializer::CopyItems() function (used by the wxXmlSerializer copy constructor).


Member Enumeration Documentation

Enumerator:
searchDFS 

Depth-First-Search algorithm.

searchBFS 

Breadth-First-Search algorithm.


Constructor & Destructor Documentation

xsSerializable::xsSerializable (  ) 

Constructor.

xsSerializable::xsSerializable ( const xsSerializable obj  ) 

Copy constructor.

xsSerializable::~xsSerializable (  ) 

Destructor.


Member Function Documentation

xsSerializable* xsSerializable::AddChild ( xsSerializable child  ) 

Add serializable child object to this object.

Parameters:
child Pointer to added child object (must NOT be NULL)
Returns:
Pointer to to the added child object
void xsSerializable::AddProperty ( xsProperty property  ) 

Add new property to the property list.

Parameters:
property Pointer to added property object
See also:
xsProperty
virtual void xsSerializable::Deserialize ( wxXmlNode *  node  )  [protected, virtual]

Deserialize object properties from the given XML node. The routine is automatically called by the framework and cares about deserialization of all defined properties.

Note that default implementation automatically deserializes all class data members marked by appropriate macros. If some non-standard class member should be deserialized as well, the source code of derived function implementation can be as in following example.

Parameters:
node Pointer to a source XML node containig the property nodes

Example code:

 void DerivedFrom_xsSerializable::Deserialize(wxXmlNode* node)
 {
      // call base class's deserialization rountine (if necessary...)
      xsSerializable::Deserialize(node);

      // iterate through all custom property nodes
      wxXmlNode *propNode = node->GetChildren();
      while(propNode)
      {
          if(propNode->GetName() == wxT("some_property_field_name"))
          {
              // read the node content and convert it to a proper data type
          }
          propNode = propNode->GetNext();
      }
 }
void xsSerializable::DeserializeObject ( wxXmlNode *  node  ) 

Deserialize marked class data members (properties) from appropriate fields of given parent 'object' XML node.

Parameters:
node Pointer to parent 'object' XML node
void xsSerializable::EnableCloning ( bool  enab  )  [inline]

Enable/disable object cloning.

Parameters:
enab TRUE if the object can be cloned, otherwise FALSE
void xsSerializable::EnablePropertySerialization ( const wxString &  field,
bool  enab 
)

Enable/disable serialization of given property.

Parameters:
field Property name
enab TRUE if the property should be serialized, otherwise FALSE
void xsSerializable::EnableSerialization ( bool  enab  )  [inline]

Enable/disable object serialization.

Parameters:
enab TRUE if the object should be serialized, otherwise FALSE
xsSerializable* xsSerializable::GetChild ( long  id,
bool  recursive = xsNORECURSIVE 
)

Get child item with given ID if exists.

Parameters:
id ID of searched child item
recursive If TRUE then the child shape will be searched recursivelly
Returns:
Pointer to first child with given ID if pressent, otherwise NULL
void xsSerializable::GetChildren ( wxClassInfo *  type,
SerializableList &  list 
)

Get children of given type.

Parameters:
type Child object type (if NULL then all children are returned)
list Reference to a list where all found child objects will be appended
SerializableList& xsSerializable::GetChildrenList (  )  [inline]

Get list of children (serializable objects) of this object.

Returns:
Reference to a list with child serializable objects (can be empty)
void xsSerializable::GetChildrenRecursively ( wxClassInfo *  type,
SerializableList &  list,
SEARCHMODE  mode = searchBFS 
)

Get all children of given type recursively (i.e. children of children of .... ).

Parameters:
type Get only children of given type (if NULL then all children are returned)
list Reference to a list where all found child objects will be appended
mode Search mode. User can choose Depth-First-Search or Breadth-First-Search algorithm (BFS is default)
See also:
SEARCHMODE
xsSerializable* xsSerializable::GetFirstChild ( wxClassInfo *  type  ) 

Get first serializable child object of given type.

Parameters:
type Child object type (can be NULL for any type)
Returns:
Pointer to child object if exists, otherwise NULL
xsSerializable* xsSerializable::GetFirstChild (  ) 

Get first serializable child object.

Returns:
Pointer to child object if exists, otherwise NULL
SerializableList::compatibility_iterator xsSerializable::GetFirstChildNode (  )  const [inline]

Get pointer to list node containing first serializable child object.

long xsSerializable::GetId (  )  const [inline]

Get object ID.

Returns:
ID value or -1 if the ID hasn't been set yet
xsSerializable* xsSerializable::GetLastChild ( wxClassInfo *  type  ) 

Get last serializable child object of given type.

Parameters:
type Child object type (can be NULL for any type)
Returns:
Pointer to child object if exists, otherwise NULL
xsSerializable* xsSerializable::GetLastChild (  ) 

Get last serializable child object.

Returns:
Pointer to child object if exists, otherwise NULL
SerializableList::compatibility_iterator xsSerializable::GetLastChildNode (  )  const [inline]

Get pointer to list node containing last serializable child object.

xsSerializable* xsSerializable::GetParent (  )  [inline]

Get serializable parent object.

Returns:
Pointer to serializable parent object if exists, otherwise NULL
wxXmlSerializer* xsSerializable::GetParentManager (  )  [inline]

Get parent data manager (instance of wxXmlSerializer).

Returns:
Pointer to parent data manager if set, otherwise NULL
PropertyList& xsSerializable::GetProperties (  )  [inline]

Get reference to properties list.

See also:
xsProperty
xsProperty* xsSerializable::GetProperty ( const wxString &  field  ) 

Get serialized property of given name.

Returns:
Pointer to the property object if exists, otherwise NULL
See also:
xsProperty
xsSerializable* xsSerializable::GetSibbling ( wxClassInfo *  type  ) 

Get next serializable sibbling object of given type.

Parameters:
type Child object type (can be NULL for any type)
Returns:
Pointer to sibbling object if exists, otherwise NULL
xsSerializable* xsSerializable::GetSibbling (  ) 

Get next serializable sibbling object.

Returns:
Pointer to sibbling object if exists, otherwise NULL
bool xsSerializable::HasChildren (  )  const [inline]

Function finds out whether this serializable item has some children.

Returns:
TRUE if the parent shape has children, otherwise FALSE
void xsSerializable::InitChild ( xsSerializable child  )  [protected]

Initialize new child object.

Parameters:
child Pointer to new child object
xsSerializable* xsSerializable::InsertChild ( size_t  pos,
xsSerializable child 
)

Insert serializable child object to this object at given position.

Parameters:
pos Zero-based position
child Pointer to added child object (must NOT be NULL)
Returns:
Pointer to to the added child object
bool xsSerializable::IsCloningEnabled (  )  const [inline]

Returns information whether the object can be cloned or not.

bool xsSerializable::IsPropertySerialized ( const wxString &  field  ) 

Returns information whether the given property is serialized or not.

Parameters:
field Name of examined property
bool xsSerializable::IsSerialized (  )  const [inline]

Returns information whether the object can be serialized or not.

xsSerializable* xsSerializable::operator<< ( xsSerializable child  ) 

Add serializable child object to this object.

Parameters:
child Pointer to added child object (should NOT be NULL)
Returns:
Pointer to added object
void xsSerializable::RemoveProperty ( xsProperty property  ) 

Remove given property from the property list.

Parameters:
property Pointer to existing property.
See also:
xsProperty, GetProperty()
void xsSerializable::Reparent ( xsSerializable parent  ) 

Assign this object as a child to given parent object.

Parameters:
parent Pointer to new parent object (must NOT be NULL)
virtual wxXmlNode* xsSerializable::Serialize ( wxXmlNode *  node  )  [protected, virtual]

Serialize stored properties to the given XML node. The serialization routine is automatically called by the framework and cares about serialization of all defined properties.

Note that default implementation automatically serializes all class data members marked by appropriate macros. If some non-standard class member should be serialized as well, the source code of derived function implementation can be as in following example.

Parameters:
node Pointer to XML node where the property nodes will be appended to

Example code:

 wxXmlNode* DerivedFrom_xsSerializable::Serialize(wxXmlNode* node)
 {
     if(node)
     {
         // call base class's serialization routine
         node = xsSeralizable::Serialize(node);

         // serialize custom property
         xsPropertyIO::AddPropertyNode(node, wxT("some_property_field_name"), wxT("string_repr_of_its_value"));
     }
     // return updated node
     return node;
 }
wxXmlNode* xsSerializable::SerializeObject ( wxXmlNode *  node  ) 

Create new 'object' XML node and serialize all marked class data members (properties) into it.

Parameters:
node Pointer to parent XML node
Returns:
Pointer to modified parent XML node
void xsSerializable::SetId ( long  id  ) 

Set ID of this object. Can be used for further objects' handling by wxXmlSerializer class (default ID value is -1). This functions should NOT be used directly; it is called by wxXmlSerializer object in the case that this serializable object is attached to another one (or directly to root node of wxXmlSerializer) by wxXmlSerializer::AddItem() member function.

void xsSerializable::SetParent ( xsSerializable parent  )  [inline]

Set serializable parent object.

Parameters:
parent Pointer to parent object
void xsSerializable::SetParentManager ( wxXmlSerializer parent  )  [inline]

Set parent data manager.

Parameters:
parent Pointer to parent data manager
xsSerializable::XS_DECLARE_CLONABLE_CLASS ( xsSerializable   ) 

Friends And Related Function Documentation

friend class wxXmlSerializer [friend]

Member Data Documentation

bool xsSerializable::m_fClone [protected]

Object cloning flag.

bool xsSerializable::m_fSerialize [protected]

Object serialization flag.

SerializableList xsSerializable::m_lstChildItems [protected]

List of child objects.

PropertyList xsSerializable::m_lstProperties [protected]

List of serialized properties.

long xsSerializable::m_nId [private]

Object ID.

Pointer to parent serializable object.

Pointer to parent data manager.


The documentation for this class was generated from the following file:
Generated by  doxygen 1.6.3