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