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