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 WXDLLIMPEXP_BASE wxWriter ;
  47 class WXDLLIMPEXP_BASE wxReader ;
  48
  49 class WXDLLIMPEXP_BASE 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) , wxxVariantArray &WXUNUSED(metadata)) { 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 wxObject *WXUNUSED(object), 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 wxObject *WXUNUSED(object), 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 WXDLLIMPEXP_BASE 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 , wxxVariantArray &WXUNUSED(metadata)) ;
  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 , wxxVariantArray &metadata ) = 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 WriteOneProperty( const wxObject *obj , const wxClassInfo* ci , const wxPropertyInfo* pi , wxPersister *persister , wxWriterInternalPropertiesData *data ) ;
 146     void WriteObject(const wxObject *object, const wxClassInfo *classInfo , wxPersister *persister , bool isEmbedded, wxxVariantArray &metadata ) ;
 147     void FindConnectEntry(const wxEvtHandler * evSource,const wxDelegateTypeInfo* dti, const wxObject* &sink , const wxHandlerInfo *&handler) ;
 148 } ;
 149
 150
 151 /*
 152 Streaming callbacks for depersisting XML to code, or running objects
 153 */
 154
 155 class WXDLLIMPEXP_BASE wxDepersister ;
 156
 157 /*
 158 wxReader handles streaming in a class from a arbitrary format. While walking through
 159 it issues calls out to interfaces to depersist the guts from the underlying storage format.
 160 */
 161
 162 class WXDLLIMPEXP_BASE wxReader : public wxObject
 163 {
 164 public :
 165     wxReader() ;
 166     ~wxReader() ;
 167
 168     // the only thing wxReader knows about is the class info by object ID
 169     wxClassInfo *GetObjectClassInfo(int objectID) ;
 170     bool HasObjectClassInfo( int objectID ) ;
 171     void SetObjectClassInfo(int objectID, wxClassInfo* classInfo);
 172
 173     // Reads the component the reader is pointed at from the underlying format.
 174     // The return value is the root object ID, which can
 175     // then be used to ask the depersister about that object
 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     // allocate the new object on the heap, that object will have the passed in ID
 192     virtual void AllocateObject(int objectID, wxClassInfo *classInfo, wxxVariantArray &metadata) = 0;
 193
 194     // initialize the already allocated object having the ID objectID with the Create method
 195     // creation parameters which are objects are having their Ids passed in objectIDValues
 196     // having objectId <> wxInvalidObjectID
 197
 198     virtual void CreateObject(int objectID,
 199         const wxClassInfo *classInfo,
 200         int paramCount,
 201         wxxVariant *VariantValues ,
 202         int *objectIDValues ,
 203         const wxClassInfo **objectClassInfos ,
 204         wxxVariantArray &metadata) = 0;
 205
 206     // construct the new object on the heap, that object will have the passed in ID (for objects that
 207     // don't support allocate-create type of creation)
 208     // creation parameters which are objects are having their Ids passed in objectIDValues
 209     // having objectId <> wxInvalidObjectID
 210
 211     virtual void ConstructObject(int objectID,
 212         const wxClassInfo *classInfo,
 213         int paramCount,
 214         wxxVariant *VariantValues ,
 215         int *objectIDValues ,
 216         const wxClassInfo **objectClassInfos ,
 217         wxxVariantArray &metadata) = 0;
 218
 219     // destroy the heap-allocated object having the ID objectID, this may be used if an object
 220     // is embedded in another object and set via value semantics, so the intermediate
 221     // object can be destroyed after safely
 222     virtual void DestroyObject(int objectID, wxClassInfo *classInfo) = 0;
 223
 224     // set the corresponding property
 225     virtual void SetProperty(int objectID,
 226         const wxClassInfo *classInfo,
 227         const wxPropertyInfo* propertyInfo ,
 228         const wxxVariant &VariantValue) = 0;
 229
 230     // sets the corresponding property (value is an object)
 231     virtual void SetPropertyAsObject(int objectID,
 232         const wxClassInfo *classInfo,
 233         const wxPropertyInfo* propertyInfo ,
 234         int valueObjectId) = 0;
 235
 236     // adds an element to a property collection
 237     virtual void AddToPropertyCollection( int objectID ,
 238         const wxClassInfo *classInfo,
 239         const wxPropertyInfo* propertyInfo ,
 240         const wxxVariant &VariantValue) = 0;
 241
 242     // sets the corresponding property (value is an object)
 243     virtual void AddToPropertyCollectionAsObject(int objectID,
 244         const wxClassInfo *classInfo,
 245         const wxPropertyInfo* propertyInfo ,
 246         int valueObjectId) = 0;
 247
 248     // sets the corresponding event handler
 249     virtual void SetConnect(int EventSourceObjectID,
 250         const wxClassInfo *EventSourceClassInfo,
 251         const wxPropertyInfo *delegateInfo ,
 252         const wxClassInfo *EventSinkClassInfo ,
 253         const wxHandlerInfo* handlerInfo ,
 254         int EventSinkObjectID ) = 0;
 255 };
 256
 257 /*
 258 wxRuntimeDepersister implements the callbacks that will depersist
 259 an object into a running memory image, as opposed to writing
 260 C++ initialization code to bring the object to life.
 261 */
 262
 263 class WXDLLIMPEXP_BASE wxRuntimeDepersister : public wxDepersister
 264 {
 265     struct wxRuntimeDepersisterInternal ;
 266     wxRuntimeDepersisterInternal * m_data ;
 267 public :
 268     wxRuntimeDepersister();
 269     virtual ~wxRuntimeDepersister();
 270
 271     // returns the object having the corresponding ID fully constructed
 272     wxObject *GetObject(int objectID) ;
 273
 274     // allocate the new object on the heap, that object will have the passed in ID
 275     virtual void AllocateObject(int objectID, wxClassInfo *classInfo ,
 276         wxxVariantArray &metadata) ;
 277
 278     // initialize the already allocated object having the ID objectID with the Create method
 279     // creation parameters which are objects are having their Ids passed in objectIDValues
 280     // having objectId <> wxInvalidObjectID
 281
 282     virtual void CreateObject(int objectID,
 283         const wxClassInfo *classInfo,
 284         int paramCount,
 285         wxxVariant *VariantValues ,
 286         int *objectIDValues,
 287         const wxClassInfo **objectClassInfos ,
 288         wxxVariantArray &metadata
 289         ) ;
 290
 291     // construct the new object on the heap, that object will have the passed in ID (for objects that
 292     // don't support allocate-create type of creation)
 293     // creation parameters which are objects are having their Ids passed in objectIDValues
 294     // having objectId <> wxInvalidObjectID
 295
 296     virtual void ConstructObject(int objectID,
 297         const wxClassInfo *classInfo,
 298         int paramCount,
 299         wxxVariant *VariantValues ,
 300         int *objectIDValues ,
 301         const wxClassInfo **objectClassInfos ,
 302         wxxVariantArray &metadata) ;
 303
 304     // destroy the heap-allocated object having the ID objectID, this may be used if an object
 305     // is embedded in another object and set via value semantics, so the intermediate
 306     // object can be destroyed after safely
 307     virtual void DestroyObject(int objectID, wxClassInfo *classInfo) ;
 308
 309     // set the corresponding property
 310     virtual void SetProperty(int objectID,
 311         const wxClassInfo *classInfo,
 312         const wxPropertyInfo* propertyInfo ,
 313         const wxxVariant &variantValue);
 314
 315     // sets the corresponding property (value is an object)
 316     virtual void SetPropertyAsObject(int objectId,
 317         const wxClassInfo *classInfo,
 318         const wxPropertyInfo* propertyInfo ,
 319         int valueObjectId) ;
 320
 321     // adds an element to a property collection
 322     virtual void AddToPropertyCollection( int objectID ,
 323         const wxClassInfo *classInfo,
 324         const wxPropertyInfo* propertyInfo ,
 325         const wxxVariant &VariantValue) ;
 326
 327     // sets the corresponding property (value is an object)
 328     virtual void AddToPropertyCollectionAsObject(int objectID,
 329         const wxClassInfo *classInfo,
 330         const wxPropertyInfo* propertyInfo ,
 331         int valueObjectId) ;
 332
 333     // sets the corresponding event handler
 334     virtual void SetConnect(int eventSourceObjectID,
 335         const wxClassInfo *eventSourceClassInfo,
 336         const wxPropertyInfo *delegateInfo ,
 337         const wxClassInfo *eventSinkClassInfo ,
 338         const wxHandlerInfo* handlerInfo ,
 339         int eventSinkObjectID ) ;
 340 };
 341
 342 /*
 343 wxDepersisterCode implements the callbacks that will depersist
 344 an object into a C++ initialization function. this will move to
 345 a utility lib soon
 346 */
 347
 348 class WXDLLIMPEXP_BASE wxTextOutputStream ;
 349
 350 class WXDLLIMPEXP_BASE wxCodeDepersister : public wxDepersister
 351 {
 352 private :
 353     struct wxCodeDepersisterInternal ;
 354     wxCodeDepersisterInternal * m_data ;
 355     wxTextOutputStream *m_fp;
 356     wxString ValueAsCode( const wxxVariant &param ) ;
 357 public:
 358     wxCodeDepersister(wxTextOutputStream *out);
 359     virtual ~wxCodeDepersister();
 360
 361     // allocate the new object on the heap, that object will have the passed in ID
 362     virtual void AllocateObject(int objectID, wxClassInfo *classInfo ,
 363         wxxVariantArray &metadata) ;
 364
 365     // initialize the already allocated object having the ID objectID with the Create method
 366     // creation parameters which are objects are having their Ids passed in objectIDValues
 367     // having objectId <> wxInvalidObjectID
 368
 369     virtual void CreateObject(int objectID,
 370         const wxClassInfo *classInfo,
 371         int paramCount,
 372         wxxVariant *variantValues ,
 373         int *objectIDValues,
 374         const wxClassInfo **objectClassInfos ,
 375         wxxVariantArray &metadata
 376         ) ;
 377
 378      // construct the new object on the heap, that object will have the passed in ID (for objects that
 379     // don't support allocate-create type of creation)
 380     // creation parameters which are objects are having their Ids passed in objectIDValues
 381     // having objectId <> wxInvalidObjectID
 382
 383     virtual void ConstructObject(int objectID,
 384         const wxClassInfo *classInfo,
 385         int paramCount,
 386         wxxVariant *VariantValues ,
 387         int *objectIDValues ,
 388         const wxClassInfo **objectClassInfos ,
 389         wxxVariantArray &metadata) ;
 390
 391     // destroy the heap-allocated object having the ID objectID, this may be used if an object
 392     // is embedded in another object and set via value semantics, so the intermediate
 393     // object can be destroyed after safely
 394     virtual void DestroyObject(int objectID, wxClassInfo *classInfo) ;
 395
 396     // set the corresponding property
 397     virtual void SetProperty(int objectID,
 398         const wxClassInfo *classInfo,
 399         const wxPropertyInfo* propertyInfo ,
 400         const wxxVariant &variantValue);
 401
 402     // sets the corresponding property (value is an object)
 403     virtual void SetPropertyAsObject(int objectId,
 404         const wxClassInfo *classInfo,
 405         const wxPropertyInfo* propertyInfo ,
 406         int valueObjectId) ;
 407
 408     // adds an element to a property collection
 409     virtual void AddToPropertyCollection( int objectID ,
 410         const wxClassInfo *classInfo,
 411         const wxPropertyInfo* propertyInfo ,
 412         const wxxVariant &VariantValue) ;
 413
 414     // sets the corresponding property (value is an object)
 415     virtual void AddToPropertyCollectionAsObject(int objectID,
 416         const wxClassInfo *classInfo,
 417         const wxPropertyInfo* propertyInfo ,
 418         int valueObjectId) ;
 419
 420     // sets the corresponding event handler
 421     virtual void SetConnect(int eventSourceObjectID,
 422         const wxClassInfo *eventSourceClassInfo,
 423         const wxPropertyInfo *delegateInfo ,
 424         const wxClassInfo *eventSinkClassInfo ,
 425         const wxHandlerInfo* handlerInfo ,
 426         int eventSinkObjectID ) ;
 427 };
 428
 429 #endif // wxUSE_EXTENDED_RTTI
 430
 431 #endif