interface/wx/object.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        object.h
   3 // Purpose:     interface of wxObjectRefData
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxObjectRefData
  11
  12     This class is used to store reference-counted data.
  13
  14     Derive classes from this to store your own data. When retrieving information
  15     from a wxObject's reference data, you will need to cast to your own derived class.
  16
  17     @b Example:
  18
  19     @code
  20     // include file
  21
  22     class MyCar: public wxObject
  23     {
  24     public:
  25         MyCar() { }
  26         MyCar( int price );
  27
  28         bool IsOk() const { return m_refData != NULL; }
  29
  30         bool operator == ( const MyCar& car ) const;
  31         bool operator != (const MyCar& car) const { return !(*this == car); }
  32
  33         void SetPrice( int price );
  34         int GetPrice() const;
  35
  36     protected:
  37         virtual wxObjectRefData *CreateRefData() const;
  38         virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const;
  39
  40         DECLARE_DYNAMIC_CLASS(MyCar)
  41     };
  42
  43
  44     // implementation
  45
  46     class MyCarRefData: public wxObjectRefData
  47     {
  48     public:
  49         MyCarRefData()
  50         {
  51             m_price = 0;
  52         }
  53
  54         MyCarRefData( const MyCarRefData& data )
  55             : wxObjectRefData()
  56         {
  57             m_price = data.m_price;
  58         }
  59
  60         bool operator == (const MyCarRefData& data) const
  61         {
  62             return m_price == data.m_price;
  63         }
  64
  65         int m_price;
  66     };
  67
  68
  69     #define M_CARDATA ((MyCarRefData *)m_refData)
  70
  71     IMPLEMENT_DYNAMIC_CLASS(MyCar,wxObject)
  72
  73     MyCar::MyCar( int price )
  74     {
  75         m_refData = new MyCarRefData();
  76         M_CARDATA->m_price = price;
  77     }
  78
  79     wxObjectRefData *MyCar::CreateRefData() const
  80     {
  81         return new MyCarRefData;
  82     }
  83
  84     wxObjectRefData *MyCar::CloneRefData(const wxObjectRefData *data) const
  85     {
  86         return new MyCarRefData(*(MyCarRefData *)data);
  87     }
  88
  89     bool MyCar::operator == ( const MyCar& car ) const
  90     {
  91         if (m_refData == car.m_refData) return true;
  92
  93         if (!m_refData || !car.m_refData) return false;
  94
  95         return ( *(MyCarRefData*)m_refData == *(MyCarRefData*)car.m_refData );
  96     }
  97
  98     void MyCar::SetPrice( int price )
  99     {
 100         UnShare();
 101
 102         M_CARDATA->m_price = price;
 103     }
 104
 105     int MyCar::GetPrice() const
 106     {
 107         wxCHECK_MSG( IsOk(), -1, "invalid car" );
 108
 109         return (M_CARDATA->m_price);
 110     }
 111     @endcode
 112
 113
 114     @library{wxbase}
 115     @category{rtti}
 116
 117     @see wxObject, wxObjectDataPtr<T>, @ref overview_refcount
 118 */
 119 class wxObjectRefData
 120 {
 121 protected:
 122     /**
 123         Destructor.
 124
 125         It's declared @c protected so that wxObjectRefData instances
 126         will never be destroyed directly but only as result of a DecRef() call.
 127     */
 128     virtual ~wxObjectRefData();
 129
 130 public:
 131     /**
 132         Default constructor. Initialises the internal reference count to 1.
 133     */
 134     wxObjectRefData();
 135
 136     /**
 137         Decrements the reference count associated with this shared data and, if
 138         it reaches zero, destroys this instance of wxObjectRefData releasing its
 139         memory.
 140
 141         Please note that after calling this function, the caller should
 142         absolutely avoid to use the pointer to this instance since it may not be
 143         valid anymore.
 144     */
 145     void DecRef();
 146
 147     /**
 148         Returns the reference count associated with this shared data.
 149
 150         When this goes to zero during a DecRef() call, the object will auto-free itself.
 151     */
 152     int GetRefCount() const;
 153
 154     /**
 155         Increments the reference count associated with this shared data.
 156     */
 157     void IncRef();
 158 };
 159
 160
 161
 162 /**
 163     @class wxObject
 164
 165     This is the root class of many of the wxWidgets classes.
 166
 167     It declares a virtual destructor which ensures that destructors get called
 168     for all derived class objects where necessary.
 169
 170     wxObject is the hub of a dynamic object creation scheme, enabling a program
 171     to create instances of a class only knowing its string class name, and to
 172     query the class hierarchy.
 173
 174     The class contains optional debugging versions of @b new and @b delete, which
 175     can help trace memory allocation and deallocation problems.
 176
 177     wxObject can be used to implement @ref overview_refcount "reference counted"
 178     objects, such as wxPen, wxBitmap and others
 179     (see @ref overview_refcount_list "this list").
 180
 181     @library{wxbase}
 182     @category{rtti}
 183
 184     @see wxClassInfo, @ref overview_debugging, wxObjectRefData
 185 */
 186 class wxObject
 187 {
 188 public:
 189
 190     wxObject();
 191
 192     /**
 193         Copy ctor.
 194     */
 195     wxObject(const wxObject& other);
 196
 197
 198     /**
 199         Destructor.
 200
 201         Performs dereferencing, for those objects that use reference counting.
 202     */
 203     virtual ~wxObject();
 204
 205     /**
 206         This virtual function is redefined for every class that requires run-time
 207         type information, when using the ::DECLARE_CLASS macro (or similar).
 208     */
 209     virtual wxClassInfo* GetClassInfo() const;
 210
 211     /**
 212         Returns the wxObject::m_refData pointer, i.e. the data referenced by this object.
 213
 214         @see Ref(), UnRef(), wxObject::m_refData, SetRefData(), wxObjectRefData
 215     */
 216     wxObjectRefData* GetRefData() const;
 217
 218     /**
 219         Determines whether this class is a subclass of (or the same class as)
 220         the given class.
 221
 222         Example:
 223
 224         @code
 225         bool tmp = obj->IsKindOf(CLASSINFO(wxFrame));
 226         @endcode
 227
 228         @param info
 229             A pointer to a class information object, which may be obtained
 230             by using the ::CLASSINFO macro.
 231
 232         @return @true if the class represented by info is the same class as this
 233                  one or is derived from it.
 234     */
 235     bool IsKindOf(const wxClassInfo* info) const;
 236
 237     /**
 238         Returns @true if this object has the same data pointer as @a obj.
 239
 240         Notice that @true is returned if the data pointers are @NULL in both objects.
 241
 242         This function only does a @e shallow comparison, i.e. it doesn't compare
 243         the objects pointed to by the data pointers of these objects.
 244
 245         @see @ref overview_refcount
 246     */
 247     bool IsSameAs(const wxObject& obj) const;
 248
 249     /**
 250         Makes this object refer to the data in @a clone.
 251
 252         @param clone
 253             The object to 'clone'.
 254
 255         @remarks First this function calls UnRef() on itself to decrement
 256                  (and perhaps free) the data it is currently referring to.
 257                  It then sets its own wxObject::m_refData to point to that of @a clone,
 258                  and increments the reference count inside the data.
 259
 260         @see UnRef(), SetRefData(), GetRefData(), wxObjectRefData
 261     */
 262     void Ref(const wxObject& clone);
 263
 264     /**
 265         Sets the wxObject::m_refData pointer.
 266
 267         @see Ref(), UnRef(), GetRefData(), wxObjectRefData
 268     */
 269     void SetRefData(wxObjectRefData* data);
 270
 271     /**
 272         Decrements the reference count in the associated data, and if it is zero,
 273         deletes the data.
 274
 275         The wxObject::m_refData member is set to @NULL.
 276
 277         @see Ref(), SetRefData(), GetRefData(), wxObjectRefData
 278     */
 279     void UnRef();
 280
 281     /**
 282         Ensure that this object's data is not shared with any other object.
 283
 284         If we have no data, it is created using CreateRefData() below,
 285         if we have shared data, it is copied using CloneRefData(),
 286         otherwise nothing is done.
 287     */
 288     void UnShare();
 289
 290     /**
 291         The @e delete operator is defined for debugging versions of the library only,
 292         when the identifier @c __WXDEBUG__ is defined.
 293
 294         It takes over memory deallocation, allowing wxDebugContext operations.
 295     */
 296     void operator delete(void *buf);
 297
 298     /**
 299         The @e new operator is defined for debugging versions of the library only, when
 300         the identifier @c __WXDEBUG__ is defined.
 301
 302         It takes over memory allocation, allowing wxDebugContext operations.
 303     */
 304     void* operator new(size_t size, const wxString& filename = NULL, int lineNum = 0);
 305
 306 protected:
 307
 308     /**
 309         Pointer to an object which is the object's reference-counted data.
 310
 311         @see Ref(), UnRef(), SetRefData(), GetRefData(), wxObjectRefData
 312     */
 313     wxObjectRefData*  m_refData;
 314 };
 315
 316
 317
 318 /**
 319     @class wxClassInfo
 320
 321     This class stores meta-information about classes.
 322
 323     Instances of this class are not generally defined directly by an application,
 324     but indirectly through use of macros such as ::DECLARE_DYNAMIC_CLASS and
 325     ::IMPLEMENT_DYNAMIC_CLASS.
 326
 327     @library{wxbase}
 328     @category{rtti}
 329
 330     @see @ref overview_rtti_classinfo, wxObject
 331 */
 332 class wxClassInfo
 333 {
 334 public:
 335     /**
 336         Constructs a wxClassInfo object.
 337
 338         The supplied macros implicitly construct objects of this class, so there is no
 339         need to create such objects explicitly in an application.
 340     */
 341     wxClassInfo(const wxChar* className,
 342                 const wxClassInfo* baseClass1,
 343                 const wxClassInfo* baseClass2,
 344                 int size, wxObjectConstructorFn fn);
 345
 346     /**
 347         Creates an object of the appropriate kind.
 348
 349         @return @NULL if the class has not been declared dynamically creatable
 350                  (typically, this happens for abstract classes).
 351     */
 352     wxObject* CreateObject() const;
 353
 354     /**
 355         Finds the wxClassInfo object for a class with the given @a name.
 356     */
 357     static wxClassInfo* FindClass(wxChar* name);
 358
 359     /**
 360         Returns the name of the first base class (@NULL if none).
 361     */
 362     const wxChar* GetBaseClassName1() const;
 363
 364     /**
 365         Returns the name of the second base class (@NULL if none).
 366     */
 367     const wxChar* GetBaseClassName2() const;
 368
 369     /**
 370         Returns the string form of the class name.
 371     */
 372     const wxChar* GetClassName() const;
 373
 374     /**
 375         Returns the size of the class.
 376     */
 377     int GetSize() const;
 378
 379     /**
 380         Initializes pointers in the wxClassInfo objects for fast execution of IsKindOf().
 381         Called in base wxWidgets library initialization.
 382     */
 383     static void InitializeClasses();
 384
 385     /**
 386         Returns @true if this class info can create objects of the associated class.
 387     */
 388     bool IsDynamic() const;
 389
 390     /**
 391         Returns @true if this class is a kind of (inherits from) the given class.
 392     */
 393     bool IsKindOf(const wxClassInfo* info) const;
 394 };
 395
 396
 397
 398 /**
 399
 400     This is helper template class primarily written to avoid memory leaks because of
 401     missing calls to wxObjectRefData::DecRef().
 402
 403     Despite the name this template can actually be used as a smart pointer for any
 404     class implementing the reference counting interface which only consists of the two
 405     methods @b T::IncRef() and @b T::DecRef().
 406
 407     The difference to wxSharedPtr<T> is that wxObjectDataPtr<T> relies on the reference
 408     counting to be in the class pointed to where instead wxSharedPtr<T> implements the
 409     reference counting itself.
 410
 411
 412     @b Example:
 413
 414     @code
 415     class MyCarRefData: public wxObjectRefData
 416     {
 417     public:
 418         MyCarRefData()  { m_price = 0; }
 419
 420         MyCarRefData( const MyCarRefData& data )
 421             : wxObjectRefData()
 422         {
 423             m_price = data.m_price;
 424         }
 425
 426         void SetPrice( int price )  { m_price = price; }
 427         int GetPrice()              { return m_price; }
 428
 429     protected:
 430         int m_price;
 431     };
 432
 433     class MyCar
 434     {
 435     public:
 436         MyCar( int price ) : m_data( new MyCarRefData )
 437         {
 438             m_data->SetPrice( price );
 439         }
 440
 441         MyCar& operator =( const MyCar& tocopy )
 442         {
 443             m_data = tocopy.m_data;
 444             return *this;
 445         }
 446
 447         bool operator == ( const MyCar& other ) const
 448         {
 449             if (m_data.get() == other.m_data.get()) return true;
 450             return (m_data->GetPrice() == other.m_data->GetPrice());
 451         }
 452
 453         void SetPrice( int price )
 454         {
 455            UnShare();
 456            m_data->SetPrice( price );
 457         }
 458
 459         int GetPrice() const
 460         {
 461            return m_data->GetPrice();
 462         }
 463
 464         wxObjectDataPtr<MyCarRefData> m_data;
 465
 466     protected:
 467         void UnShare()
 468         {
 469             if (m_data->GetRefCount() == 1)
 470                 return;
 471
 472             m_data.reset( new MyCarRefData( *m_data ) );
 473         }
 474     };
 475     @endcode
 476
 477
 478     @library{wxbase}
 479     @category{rtti,smartpointers}
 480
 481     @see wxObject, wxObjectRefData, @ref overview_refcount, wxSharedPtr<T>,
 482          wxScopedPtr<T>, wxWeakRef<T>
 483 */
 484 class wxObjectDataPtr<T>
 485 {
 486 public:
 487     /**
 488         Constructor.
 489
 490         @a ptr is a pointer to the reference counted object to which this class points.
 491         If @a ptr is not NULL @b T::IncRef() will be called on the object.
 492     */
 493     wxObjectDataPtr<T>(T* ptr = NULL);
 494
 495     /**
 496         This copy constructor increases the count of the reference counted object to
 497         which @a tocopy points and then this class will point to, as well.
 498     */
 499     wxObjectDataPtr<T>(const wxObjectDataPtr<T>& tocopy);
 500
 501
 502     /**
 503         Decreases the reference count of the object to which this class points.
 504     */
 505     ~wxObjectDataPtr<T>();
 506
 507     /**
 508         Gets a pointer to the reference counted object to which this class points.
 509     */
 510     T* get() const;
 511
 512     /**
 513         Reset this class to ptr which points to a reference counted object and
 514         calls T::DecRef() on the previously owned object.
 515     */
 516     void reset(T *ptr);
 517
 518     /**
 519         Conversion to a boolean expression (in a variant which is not
 520         convertable to anything but a boolean expression).
 521
 522         If this class contains a valid pointer it will return @true, if it contains
 523         a @NULL pointer it will return @false.
 524     */
 525     operator unspecified_bool_type() const;
 526
 527     /**
 528         Returns a reference to the object.
 529
 530         If the internal pointer is @NULL this method will cause an assert in debug mode.
 531     */
 532     T& operator*() const;
 533
 534     /**
 535         Returns a pointer to the reference counted object to which this class points.
 536
 537         If this the internal pointer is @NULL, this method will assert in debug mode.
 538     */
 539     T* operator->() const;
 540
 541     //@{
 542     /**
 543         Assignment operator.
 544     */
 545     wxObjectDataPtr<T>& operator=(const wxObjectDataPtr<T>& tocopy);
 546     wxObjectDataPtr<T>& operator=(T* ptr);
 547     //@}
 548 };
 549
 550
 551
 552 // ============================================================================
 553 // Global functions/macros
 554 // ============================================================================
 555
 556 /** @ingroup group_funcmacro_rtti */
 557 //@{
 558
 559 /**
 560     Returns a pointer to the wxClassInfo object associated with this class.
 561
 562     @header{wx/object.h}
 563 */
 564 #define CLASSINFO( className )
 565
 566 /**
 567     Used inside a class declaration to declare that the class should be made
 568     known to the class hierarchy, but objects of this class cannot be created
 569     dynamically. The same as DECLARE_ABSTRACT_CLASS().
 570
 571     @header{wx/object.h}
 572 */
 573 #define DECLARE_CLASS( className )
 574
 575 /**
 576     Used inside a class declaration to declare that the class should be
 577     made known to the class hierarchy, but objects of this class cannot be created
 578     dynamically. The same as DECLARE_CLASS().
 579
 580     @header{wx/object.h}
 581
 582     Example:
 583
 584     @code
 585     class wxCommand: public wxObject
 586     {
 587         DECLARE_ABSTRACT_CLASS(wxCommand)
 588
 589     private:
 590         ...
 591     public:
 592         ...
 593     };
 594     @endcode
 595 */
 596 #define DECLARE_ABSTRACT_CLASS( className )
 597
 598 /**
 599     Used inside a class declaration to make the class known to wxWidgets RTTI
 600     system and also declare that the objects of this class should be
 601     dynamically creatable from run-time type information. Notice that this
 602     implies that the class should have a default constructor, if this is not
 603     the case consider using DECLARE_CLASS().
 604
 605     @header{wx/object.h}
 606
 607     Example:
 608
 609     @code
 610     class wxFrame: public wxWindow
 611     {
 612     DECLARE_DYNAMIC_CLASS(wxFrame)
 613
 614     private:
 615         const wxString& frameTitle;
 616     public:
 617         ...
 618     };
 619     @endcode
 620 */
 621 #define DECLARE_DYNAMIC_CLASS( className )
 622
 623 /**
 624     Used in a C++ implementation file to complete the declaration of a class
 625     that has run-time type information. The same as IMPLEMENT_ABSTRACT_CLASS().
 626
 627     @header{wx/object.h}
 628 */
 629 #define IMPLEMENT_CLASS( className, baseClassName )
 630
 631 /**
 632     Used in a C++ implementation file to complete the declaration of a class
 633     that has run-time type information and two base classes. The same as
 634     IMPLEMENT_ABSTRACT_CLASS2().
 635
 636     @header{wx/object.h}
 637 */
 638 #define IMPLEMENT_CLASS2( className, baseClassName1, baseClassName2 )
 639
 640 /**
 641     Used in a C++ implementation file to complete the declaration of a class
 642     that has run-time type information. The same as IMPLEMENT_CLASS().
 643
 644     @header{wx/object.h}
 645
 646     Example:
 647
 648     @code
 649     IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
 650
 651     wxCommand::wxCommand(void)
 652     {
 653         ...
 654     }
 655     @endcode
 656 */
 657 #define IMPLEMENT_ABSTRACT_CLASS( className, baseClassName )
 658
 659 /**
 660     Used in a C++ implementation file to complete the declaration of a class
 661     that has run-time type information and two base classes. The same as
 662     IMPLEMENT_CLASS2().
 663
 664     @header{wx/object.h}
 665 */
 666 #define IMPLEMENT_ABSTRACT_CLASS2( className, baseClassName1, baseClassName2 )
 667
 668 /**
 669     Used in a C++ implementation file to complete the declaration of a class
 670     that has run-time type information, and whose instances can be created
 671     dynamically.
 672
 673     @header{wx/object.h}
 674
 675     Example:
 676
 677     @code
 678     IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
 679
 680     wxFrame::wxFrame(void)
 681     {
 682         ...
 683     }
 684     @endcode
 685 */
 686 #define IMPLEMENT_DYNAMIC_CLASS( className, baseClassName )
 687
 688 /**
 689     Used in a C++ implementation file to complete the declaration of a class
 690     that has run-time type information, and whose instances can be created
 691     dynamically. Use this for classes derived from two base classes.
 692
 693     @header{wx/object.h}
 694 */
 695 #define IMPLEMENT_DYNAMIC_CLASS2( className, baseClassName1, baseClassName2 )
 696
 697 /**
 698     Same as @c const_cast<T>(x) if the compiler supports const cast or @c (T)x for
 699     old compilers. Unlike wxConstCast(), the cast it to the type @c T and not to
 700     <tt>T *</tt> and also the order of arguments is the same as for the standard cast.
 701
 702     @header{wx/defs.h}
 703
 704     @see wx_reinterpret_cast(), wx_static_cast()
 705 */
 706 #define wx_const_cast(T, x)
 707
 708 /**
 709     Same as @c reinterpret_cast<T>(x) if the compiler supports reinterpret cast or
 710     @c (T)x for old compilers.
 711
 712     @header{wx/defs.h}
 713
 714     @see wx_const_cast(), wx_static_cast()
 715 */
 716 #define wx_reinterpret_cast(T, x)
 717
 718 /**
 719     Same as @c static_cast<T>(x) if the compiler supports static cast or @c (T)x for
 720     old compilers. Unlike wxStaticCast(), there are no checks being done and
 721     the meaning of the macro arguments is exactly the same as for the standard
 722     static cast, i.e. @a T is the full type name and star is not appended to it.
 723
 724     @header{wx/defs.h}
 725
 726     @see wx_const_cast(), wx_reinterpret_cast(), wx_truncate_cast()
 727 */
 728 #define wx_static_cast(T, x)
 729
 730 /**
 731     This case doesn’t correspond to any standard cast but exists solely to make
 732     casts which possibly result in a truncation of an integer value more
 733     readable.
 734
 735     @header{wx/defs.h}
 736 */
 737 #define wx_truncate_cast(T, x)
 738
 739 /**
 740     This macro expands into <tt>const_cast<classname *>(ptr)</tt> if the compiler
 741     supports const_cast or into an old, C-style cast, otherwise.
 742
 743     @header{wx/defs.h}
 744
 745     @see wx_const_cast(), wxDynamicCast(), wxStaticCast()
 746 */
 747 #define wxConstCast( ptr, classname )
 748
 749 /**
 750     This macro returns the pointer @e ptr cast to the type @e classname * if
 751     the pointer is of this type (the check is done during the run-time) or
 752     @NULL otherwise. Usage of this macro is preferred over obsoleted
 753     wxObject::IsKindOf() function.
 754
 755     The @e ptr argument may be @NULL, in which case @NULL will be returned.
 756
 757     @header{wx/object.h}
 758
 759     Example:
 760
 761     @code
 762     wxWindow *win = wxWindow::FindFocus();
 763     wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl);
 764     if ( text )
 765     {
 766         // a text control has the focus...
 767     }
 768     else
 769     {
 770         // no window has the focus or it is not a text control
 771     }
 772     @endcode
 773
 774     @see @ref overview_rtti, wxDynamicCastThis(), wxConstCast(), wxStaticCast()
 775 */
 776 #define wxDynamicCast( ptr, classname )
 777
 778 /**
 779     This macro is equivalent to <tt>wxDynamicCast(this, classname)</tt> but the latter provokes
 780     spurious compilation warnings from some compilers (because it tests whether
 781     @c this pointer is non-@NULL which is always true), so this macro should be
 782     used to avoid them.
 783
 784     @header{wx/object.h}
 785
 786     @see wxDynamicCast()
 787 */
 788 #define wxDynamicCastThis( classname )
 789
 790 /**
 791     This macro checks that the cast is valid in debug mode (an assert failure
 792     will result if wxDynamicCast(ptr, classname) == @NULL) and then returns the
 793     result of executing an equivalent of <tt>static_cast<classname *>(ptr)</tt>.
 794
 795     @header{wx/object.h}
 796
 797     @see wx_static_cast(), wxDynamicCast(), wxConstCast()
 798 */
 799 #define wxStaticCast( ptr, classname )
 800
 801 /**
 802     Creates and returns an object of the given class, if the class has been
 803     registered with the dynamic class system using DECLARE... and IMPLEMENT...
 804     macros.
 805
 806     @header{wx/object.h}
 807 */
 808 wxObject *wxCreateDynamicObject(const wxString& className);
 809
 810 //@}
 811
 812 /** @ingroup group_funcmacro_debug */
 813 //@{
 814
 815 /**
 816     This is defined in debug mode to be call the redefined new operator
 817     with filename and line number arguments. The definition is:
 818
 819     @code
 820     #define WXDEBUG_NEW new(__FILE__,__LINE__)
 821     @endcode
 822
 823     In non-debug mode, this is defined as the normal new operator.
 824
 825     @header{wx/object.h}
 826 */
 827 #define WXDEBUG_NEW( arg )
 828
 829 //@}
 830