include/wx/xtistrm.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/xtistrm.h
   3 // Purpose:     streaming runtime metadata information (extended class info)
   4 // Author:      Stefan Csomor
   5 // Modified by:
   6 // Created:     27/07/03
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 2003 Stefan Csomor
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_XTISTRMH__
  13 #define _WX_XTISTRMH__
  14
  15 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
  16 #pragma interface "xtistrm.h"
  17 #endif
  18
  19 #include "wx/wx.h"
  20
  21 #if wxUSE_EXTENDED_RTTI
  22
  23 const int wxInvalidObjectID = -2 ;
  24 const int wxNullObjectID = -1 ;
  25
  26 // Filer contains the interfaces for streaming objects in and out of XML,
  27 // rendering them either to objects in memory, or to code.  Note:  We
  28 // consider the process of generating code to be one of *depersisting* the
  29 // object from xml, *not* of persisting the object to code from an object
  30 // in memory.  This distincation can be confusing, and should be kept
  31 // in mind when looking at the property streamers and callback interfaces
  32 // listed below.
  33
  34 /*
  35 Main interfaces for streaming out objects.
  36 */
  37
  38 // ----------------------------------------------------------------------------
  39 // wxPersister
  40 //
  41 // This class will be asked during the streaming-out process about every single
  42 // property or object instance. It can veto streaming out by returning false
  43 // or modify the value before it is streamed-out.
  44 // ----------------------------------------------------------------------------
  45
  46 class wxWriter ;
  47 class wxReader ;
  48
  49 class wxPersister
  50 {
  51 public :
  52     // will be called before an object is written, may veto by returning false
  53     virtual bool BeforeWriteObject( wxWriter *WXUNUSED(writer) , const wxObject *WXUNUSED(object) , const wxClassInfo *WXUNUSED(classInfo) ) { return true ; }
  54
  55     // will be called after this object has been written, may be needed for adjusting stacks
  56     virtual void AfterWriteObject( wxWriter *WXUNUSED(writer)  , const wxObject *WXUNUSED(object) , const wxClassInfo *WXUNUSED(classInfo) ) {}
  57
  58     // will be called before a property gets written, may change the value , eg replace a concrete wxSize by wxSize( -1 , -1 ) or veto
  59     // writing that property at all by returning false
  60     virtual bool BeforeWriteProperty( wxWriter *WXUNUSED(writer)  , const wxPropertyInfo *WXUNUSED(propInfo) , wxxVariant &WXUNUSED(value) )  { return true ; }
  61
  62     // will be called before a property gets written, may change the value , eg replace a concrete wxSize by wxSize( -1 , -1 ) or veto
  63     // writing that property at all by returning false
  64     virtual bool BeforeWriteProperty( wxWriter *WXUNUSED(writer)  , const wxPropertyInfo *WXUNUSED(propInfo) , wxxVariantArray &WXUNUSED(value) )  { return true ; }
  65
  66     // will be called after a property has been written out, may be needed for adjusting stacks
  67     virtual void AfterWriteProperty( wxWriter *WXUNUSED(writer)  , const wxPropertyInfo *WXUNUSED(propInfo) ) {}
  68
  69     // will be called before this delegate gets written
  70     virtual bool BeforeWriteDelegate( wxWriter *WXUNUSED(writer) , const wxObject *WXUNUSED(object),  const wxClassInfo* WXUNUSED(classInfo) , const wxPropertyInfo *WXUNUSED(propInfo) ,
  71         const wxObject *&WXUNUSED(eventSink) , const wxHandlerInfo* &WXUNUSED(handlerInfo) ) { return true ; }
  72
  73     virtual void AfterWriteDelegate( wxWriter *WXUNUSED(writer) , const wxObject *WXUNUSED(object),  const wxClassInfo* WXUNUSED(classInfo) , const wxPropertyInfo *WXUNUSED(propInfo) ,
  74         const wxObject *&WXUNUSED(eventSink) , const wxHandlerInfo* &WXUNUSED(handlerInfo) ) { }
  75 } ;
  76
  77 class wxWriter : public wxObject
  78 {
  79 public :
  80     wxWriter() ;
  81     ~wxWriter() ;
  82
  83     // with this call you start writing out a new top-level object
  84     void WriteObject(const wxObject *object, const wxClassInfo *classInfo , wxPersister *persister , const wxString &name ) ;
  85
  86     //
  87     // Managing the object identity table a.k.a context
  88     //
  89     // these methods make sure that no object gets written twice, because sometimes multiple calls to the WriteObject will be
  90     // made without wanting to have duplicate objects written, the object identity table will be reset manually
  91
  92     virtual void ClearObjectContext() ;
  93
  94     // gets the object Id for a passed in object in the context
  95     int GetObjectID(const wxObject *obj) ;
  96
  97     // returns true if this object has already been written in this context
  98     bool IsObjectKnown( const wxObject *obj ) ;
  99
 100     //
 101     // streaming callbacks
 102     //
 103     // these callbacks really write out the values in the stream format
 104
 105     // begins writing out a new toplevel entry which has the indicated unique name
 106     virtual void DoBeginWriteTopLevelEntry( const wxString &name ) = 0 ;
 107
 108     // ends writing out a new toplevel entry which has the indicated unique name
 109     virtual void DoEndWriteTopLevelEntry( const wxString &name ) = 0 ;
 110
 111     // start of writing an object having the passed in ID
 112     virtual void DoBeginWriteObject(const wxObject *object, const wxClassInfo *classInfo, int objectID ) = 0 ;
 113
 114     // end of writing an toplevel object name param is used for unique identification within the container
 115     virtual void DoEndWriteObject(const wxObject *object, const wxClassInfo *classInfo, int objectID ) = 0 ;
 116
 117     // writes a simple property in the stream format
 118     virtual void DoWriteSimpleType( wxxVariant &value ) = 0 ;
 119
 120     // start of writing a complex property into the stream (
 121     virtual void DoBeginWriteProperty( const wxPropertyInfo *propInfo ) = 0 ;
 122
 123     // end of writing a complex property into the stream
 124     virtual void DoEndWriteProperty( const wxPropertyInfo *propInfo ) = 0;
 125
 126     virtual void DoBeginWriteElement() = 0 ;
 127     virtual void DoEndWriteElement() = 0 ;
 128     // insert an object reference to an already written object
 129     virtual void DoWriteRepeatedObject( int objectID ) = 0 ;
 130
 131     // insert a null reference
 132     virtual void DoWriteNullObject() = 0 ;
 133
 134     // writes a delegate in the stream format
 135     virtual void DoWriteDelegate( const wxObject *object,  const wxClassInfo* classInfo , const wxPropertyInfo *propInfo ,
 136         const wxObject *eventSink , int sinkObjectID , const wxClassInfo* eventSinkClassInfo , const wxHandlerInfo* handlerIndo ) = 0;
 137 private :
 138
 139     struct wxWriterInternal ;
 140     wxWriterInternal* m_data ;
 141
 142     struct wxWriterInternalPropertiesData ;
 143
 144     void WriteAllProperties( const wxObject * obj , const wxClassInfo* ci , wxPersister *persister, wxWriterInternalPropertiesData * data ) ;
 145     void WriteObject(const wxObject *object, const wxClassInfo *classInfo , wxPersister *persister , bool isEmbedded) ;
 146     void FindConnectEntry(const wxWindow * evSource,const wxDelegateTypeInfo* dti, const wxObject* &sink , const wxHandlerInfo *&handler) ;
 147 } ;
 148
 149 class wxXmlWriter : public wxWriter
 150 {
 151 public :
 152
 153     wxXmlWriter( wxXmlNode * parent ) ;
 154     ~wxXmlWriter() ;
 155
 156     //
 157     // streaming callbacks
 158     //
 159     // these callbacks really write out the values in the stream format
 160     //
 161
 162     //
 163     // streaming callbacks
 164     //
 165     // these callbacks really write out the values in the stream format
 166
 167     // begins writing out a new toplevel entry which has the indicated unique name
 168     virtual void DoBeginWriteTopLevelEntry( const wxString &name )  ;
 169
 170     // ends writing out a new toplevel entry which has the indicated unique name
 171     virtual void DoEndWriteTopLevelEntry( const wxString &name )  ;
 172
 173     // start of writing an object having the passed in ID
 174     virtual void DoBeginWriteObject(const wxObject *object, const wxClassInfo *classInfo, int objectID ) ;
 175
 176     // end of writing an toplevel object name param is used for unique identification within the container
 177     virtual void DoEndWriteObject(const wxObject *object, const wxClassInfo *classInfo, int objectID ) ;
 178
 179     // writes a simple property in the stream format
 180     virtual void DoWriteSimpleType( wxxVariant &value )  ;
 181
 182     // start of writing a complex property into the stream (
 183     virtual void DoBeginWriteProperty( const wxPropertyInfo *propInfo )  ;
 184
 185     // end of writing a complex property into the stream
 186     virtual void DoEndWriteProperty( const wxPropertyInfo *propInfo ) ;
 187
 188     virtual void DoBeginWriteElement() ;
 189     virtual void DoEndWriteElement() ;
 190
 191     // insert an object reference to an already written object
 192     virtual void DoWriteRepeatedObject( int objectID )  ;
 193
 194     // insert a null reference
 195     virtual void DoWriteNullObject()  ;
 196
 197     // writes a delegate in the stream format
 198     virtual void DoWriteDelegate( const wxObject *object,  const wxClassInfo* classInfo , const wxPropertyInfo *propInfo ,
 199         const wxObject *eventSink , int sinkObjectID , const wxClassInfo* eventSinkClassInfo , const wxHandlerInfo* handlerIndo ) ;
 200 private :
 201     struct wxXmlWriterInternal ;
 202     wxXmlWriterInternal* m_data ;
 203 } ;
 204
 205 /*
 206 Streaming callbacks for depersisting XML to code, or running objects
 207 */
 208
 209 class wxDepersister ;
 210
 211 /*
 212 wxReader handles streaming in a class from a arbitrary format. While walking through
 213 it issues calls out to interfaces to depersist the guts from the underlying storage format.
 214 */
 215
 216 class wxReader : public wxObject
 217 {
 218 public :
 219     wxReader() ;
 220     ~wxReader() ;
 221
 222     // the only thing wxReader knows about is the class info by object ID
 223     wxClassInfo *GetObjectClassInfo(int objectID) ;
 224     bool HasObjectClassInfo( int objectID ) ;
 225     void SetObjectClassInfo(int objectID, wxClassInfo* classInfo);
 226
 227     // Reads the component the reader is pointed at from the underlying format.
 228     // The return value is the root object ID, which can
 229     // then be used to ask the depersister about that object
 230     virtual int ReadObject( const wxString &name , wxDepersister *depersist ) = 0 ;
 231
 232 private :
 233     struct wxReaderInternal;
 234     wxReaderInternal *m_data;
 235 } ;
 236
 237 /*
 238 wxXmlReader handles streaming in a class from XML
 239 */
 240
 241 class wxXmlReader : public wxReader
 242 {
 243 public:
 244     wxXmlReader(wxXmlNode *parent) { m_parent = parent ; }
 245     ~wxXmlReader() {}
 246
 247     // Reads a component from XML.  The return value is the root object ID, which can
 248     // then be used to ask the depersister about that object
 249
 250     virtual int ReadObject( const wxString &name , wxDepersister *depersist ) ;
 251
 252 private :
 253     int ReadComponent(wxXmlNode *parent, wxDepersister *callbacks);
 254
 255     // accessor is only used as a temporary measure
 256     wxxVariant ReadValue(wxXmlNode *Node,
 257         wxPropertyAccessor *accessor );
 258
 259     wxXmlNode * m_parent ;
 260 };
 261
 262 // This abstract class matches the allocate-init/create model of creation of objects.
 263 // At runtime, these will create actual instances, and manipulate them.
 264 // When generating code, these will just create statements of C++
 265 // code to create the objects.
 266
 267 class wxDepersister
 268 {
 269 public :
 270     // allocate the new object on the heap, that object will have the passed in ID
 271     virtual void AllocateObject(int objectID, wxClassInfo *classInfo) = 0;
 272
 273     // initialize the already allocated object having the ID objectID with the Create method
 274     // creation parameters which are objects are having their Ids passed in objectIDValues
 275     // having objectId <> wxInvalidObjectID
 276
 277     virtual void CreateObject(int objectID,
 278         const wxClassInfo *classInfo,
 279         int paramCount,
 280         wxxVariant *VariantValues ,
 281         int *objectIDValues ,
 282         const wxClassInfo **objectClassInfos
 283         ) = 0;
 284
 285     // destroy the heap-allocated object having the ID objectID, this may be used if an object
 286     // is embedded in another object and set via value semantics, so the intermediate
 287     // object can be destroyed after safely
 288     virtual void DestroyObject(int objectID, wxClassInfo *classInfo) = 0;
 289
 290     // set the corresponding property
 291     virtual void SetProperty(int objectID,
 292         const wxClassInfo *classInfo,
 293         const wxPropertyInfo* propertyInfo ,
 294         const wxxVariant &VariantValue) = 0;
 295
 296     // sets the corresponding property (value is an object)
 297     virtual void SetPropertyAsObject(int objectID,
 298         const wxClassInfo *classInfo,
 299         const wxPropertyInfo* propertyInfo ,
 300         int valueObjectId) = 0;
 301
 302     // adds an element to a property collection
 303     virtual void AddToPropertyCollection( int objectID ,
 304         const wxClassInfo *classInfo,
 305         const wxPropertyInfo* propertyInfo ,
 306         const wxxVariant &VariantValue) = 0;
 307
 308     // sets the corresponding property (value is an object)
 309     virtual void AddToPropertyCollectionAsObject(int objectID,
 310         const wxClassInfo *classInfo,
 311         const wxPropertyInfo* propertyInfo ,
 312         int valueObjectId) = 0;
 313
 314     // sets the corresponding event handler
 315     virtual void SetConnect(int EventSourceObjectID,
 316         const wxClassInfo *EventSourceClassInfo,
 317         const wxDelegateTypeInfo *delegateInfo ,
 318         const wxClassInfo *EventSinkClassInfo ,
 319         const wxHandlerInfo* handlerInfo ,
 320         int EventSinkObjectID ) = 0;
 321 };
 322
 323 /*
 324 wxRuntimeDepersister implements the callbacks that will depersist
 325 an object into a running memory image, as opposed to writing
 326 C++ initialization code to bring the object to life.
 327 */
 328 class wxRuntimeDepersister : public wxDepersister
 329 {
 330     struct wxRuntimeDepersisterInternal ;
 331     wxRuntimeDepersisterInternal * m_data ;
 332 public :
 333     wxRuntimeDepersister() ;
 334     ~wxRuntimeDepersister() ;
 335
 336     // returns the object having the corresponding ID fully constructed
 337     wxObject *GetObject(int objectID) ;
 338
 339     // allocate the new object on the heap, that object will have the passed in ID
 340     virtual void AllocateObject(int objectID, wxClassInfo *classInfo) ;
 341
 342     // initialize the already allocated object having the ID objectID with the Create method
 343     // creation parameters which are objects are having their Ids passed in objectIDValues
 344     // having objectId <> wxInvalidObjectID
 345
 346     virtual void CreateObject(int objectID,
 347         const wxClassInfo *classInfo,
 348         int paramCount,
 349         wxxVariant *VariantValues ,
 350         int *objectIDValues,
 351         const wxClassInfo **objectClassInfos
 352         ) ;
 353
 354     // destroy the heap-allocated object having the ID objectID, this may be used if an object
 355     // is embedded in another object and set via value semantics, so the intermediate
 356     // object can be destroyed after safely
 357     virtual void DestroyObject(int objectID, wxClassInfo *classInfo) ;
 358
 359     // set the corresponding property
 360     virtual void SetProperty(int objectID,
 361         const wxClassInfo *classInfo,
 362         const wxPropertyInfo* propertyInfo ,
 363         const wxxVariant &variantValue);
 364
 365     // sets the corresponding property (value is an object)
 366     virtual void SetPropertyAsObject(int objectId,
 367         const wxClassInfo *classInfo,
 368         const wxPropertyInfo* propertyInfo ,
 369         int valueObjectId) ;
 370
 371     // adds an element to a property collection
 372     virtual void AddToPropertyCollection( int objectID ,
 373         const wxClassInfo *classInfo,
 374         const wxPropertyInfo* propertyInfo ,
 375         const wxxVariant &VariantValue) ;
 376
 377     // sets the corresponding property (value is an object)
 378     virtual void AddToPropertyCollectionAsObject(int objectID,
 379         const wxClassInfo *classInfo,
 380         const wxPropertyInfo* propertyInfo ,
 381         int valueObjectId) ;
 382
 383     // sets the corresponding event handler
 384     virtual void SetConnect(int eventSourceObjectID,
 385         const wxClassInfo *eventSourceClassInfo,
 386         const wxDelegateTypeInfo *delegateInfo ,
 387         const wxClassInfo *eventSinkClassInfo ,
 388         const wxHandlerInfo* handlerInfo ,
 389         int eventSinkObjectID ) ;
 390 };
 391
 392 /*
 393 wxDepersisterCode implements the callbacks that will depersist
 394 an object into a C++ initialization function.
 395 */
 396
 397 class wxTextOutputStream ;
 398
 399 class wxCodeDepersister : public wxDepersister
 400 {
 401 private :
 402     struct wxCodeDepersisterInternal ;
 403     wxCodeDepersisterInternal * m_data ;
 404     wxTextOutputStream *m_fp;
 405     wxString ValueAsCode( const wxxVariant &param ) ;
 406 public:
 407     wxCodeDepersister(wxTextOutputStream *out) ;
 408     ~wxCodeDepersister() ;
 409
 410     // allocate the new object on the heap, that object will have the passed in ID
 411     virtual void AllocateObject(int objectID, wxClassInfo *classInfo) ;
 412
 413     // initialize the already allocated object having the ID objectID with the Create method
 414     // creation parameters which are objects are having their Ids passed in objectIDValues
 415     // having objectId <> wxInvalidObjectID
 416
 417     virtual void CreateObject(int objectID,
 418         const wxClassInfo *classInfo,
 419         int paramCount,
 420         wxxVariant *variantValues ,
 421         int *objectIDValues,
 422         const wxClassInfo **objectClassInfos
 423         ) ;
 424
 425     // destroy the heap-allocated object having the ID objectID, this may be used if an object
 426     // is embedded in another object and set via value semantics, so the intermediate
 427     // object can be destroyed after safely
 428     virtual void DestroyObject(int objectID, wxClassInfo *classInfo) ;
 429
 430     // set the corresponding property
 431     virtual void SetProperty(int objectID,
 432         const wxClassInfo *classInfo,
 433         const wxPropertyInfo* propertyInfo ,
 434         const wxxVariant &variantValue);
 435
 436     // sets the corresponding property (value is an object)
 437     virtual void SetPropertyAsObject(int objectId,
 438         const wxClassInfo *classInfo,
 439         const wxPropertyInfo* propertyInfo ,
 440         int valueObjectId) ;
 441
 442     // adds an element to a property collection
 443     virtual void AddToPropertyCollection( int objectID ,
 444         const wxClassInfo *classInfo,
 445         const wxPropertyInfo* propertyInfo ,
 446         const wxxVariant &VariantValue) ;
 447
 448     // sets the corresponding property (value is an object)
 449     virtual void AddToPropertyCollectionAsObject(int objectID,
 450         const wxClassInfo *classInfo,
 451         const wxPropertyInfo* propertyInfo ,
 452         int valueObjectId) ;
 453
 454     // sets the corresponding event handler
 455     virtual void SetConnect(int eventSourceObjectID,
 456         const wxClassInfo *eventSourceClassInfo,
 457         const wxDelegateTypeInfo *delegateInfo ,
 458         const wxClassInfo *eventSinkClassInfo ,
 459         const wxHandlerInfo* handlerInfo ,
 460         int eventSinkObjectID ) ;
 461 };
 462
 463 #endif // wxUSE_EXTENDED_RTTI
 464
 465 #endif