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         Returns @true if this class info can create objects of the associated class.
 381     */
 382     bool IsDynamic() const;
 383
 384     /**
 385         Returns @true if this class is a kind of (inherits from) the given class.
 386     */
 387     bool IsKindOf(const wxClassInfo* info) const;
 388 };
 389
 390
 391
 392 /**
 393
 394     This is helper template class primarily written to avoid memory leaks because of
 395     missing calls to wxObjectRefData::DecRef().
 396
 397     Despite the name this template can actually be used as a smart pointer for any
 398     class implementing the reference counting interface which only consists of the two
 399     methods @b T::IncRef() and @b T::DecRef().
 400
 401     The difference to wxSharedPtr<T> is that wxObjectDataPtr<T> relies on the reference
 402     counting to be in the class pointed to where instead wxSharedPtr<T> implements the
 403     reference counting itself.
 404
 405
 406     @b Example:
 407
 408     @code
 409     class MyCarRefData: public wxObjectRefData
 410     {
 411     public:
 412         MyCarRefData()  { m_price = 0; }
 413
 414         MyCarRefData( const MyCarRefData& data )
 415             : wxObjectRefData()
 416         {
 417             m_price = data.m_price;
 418         }
 419
 420         void SetPrice( int price )  { m_price = price; }
 421         int GetPrice()              { return m_price; }
 422
 423     protected:
 424         int m_price;
 425     };
 426
 427     class MyCar
 428     {
 429     public:
 430         MyCar( int price ) : m_data( new MyCarRefData )
 431         {
 432             m_data->SetPrice( price );
 433         }
 434
 435         MyCar& operator =( const MyCar& tocopy )
 436         {
 437             m_data = tocopy.m_data;
 438             return *this;
 439         }
 440
 441         bool operator == ( const MyCar& other ) const
 442         {
 443             if (m_data.get() == other.m_data.get()) return true;
 444             return (m_data->GetPrice() == other.m_data->GetPrice());
 445         }
 446
 447         void SetPrice( int price )
 448         {
 449            UnShare();
 450            m_data->SetPrice( price );
 451         }
 452
 453         int GetPrice() const
 454         {
 455            return m_data->GetPrice();
 456         }
 457
 458         wxObjectDataPtr<MyCarRefData> m_data;
 459
 460     protected:
 461         void UnShare()
 462         {
 463             if (m_data->GetRefCount() == 1)
 464                 return;
 465
 466             m_data.reset( new MyCarRefData( *m_data ) );
 467         }
 468     };
 469     @endcode
 470
 471
 472     @library{wxbase}
 473     @category{rtti,smartpointers}
 474
 475     @see wxObject, wxObjectRefData, @ref overview_refcount, wxSharedPtr<T>,
 476          wxScopedPtr<T>, wxWeakRef<T>
 477 */
 478 class wxObjectDataPtr<T>
 479 {
 480 public:
 481     /**
 482         Constructor.
 483
 484         @a ptr is a pointer to the reference counted object to which this class points.
 485         If @a ptr is not NULL @b T::IncRef() will be called on the object.
 486     */
 487     wxObjectDataPtr<T>(T* ptr = NULL);
 488
 489     /**
 490         This copy constructor increases the count of the reference counted object to
 491         which @a tocopy points and then this class will point to, as well.
 492     */
 493     wxObjectDataPtr<T>(const wxObjectDataPtr<T>& tocopy);
 494
 495
 496     /**
 497         Decreases the reference count of the object to which this class points.
 498     */
 499     ~wxObjectDataPtr<T>();
 500
 501     /**
 502         Gets a pointer to the reference counted object to which this class points.
 503     */
 504     T* get() const;
 505
 506     /**
 507         Reset this class to ptr which points to a reference counted object and
 508         calls T::DecRef() on the previously owned object.
 509     */
 510     void reset(T *ptr);
 511
 512     /**
 513         Conversion to a boolean expression (in a variant which is not
 514         convertable to anything but a boolean expression).
 515
 516         If this class contains a valid pointer it will return @true, if it contains
 517         a @NULL pointer it will return @false.
 518     */
 519     operator unspecified_bool_type() const;
 520
 521     /**
 522         Returns a reference to the object.
 523
 524         If the internal pointer is @NULL this method will cause an assert in debug mode.
 525     */
 526     T& operator*() const;
 527
 528     /**
 529         Returns a pointer to the reference counted object to which this class points.
 530
 531         If this the internal pointer is @NULL, this method will assert in debug mode.
 532     */
 533     T* operator->() const;
 534
 535     //@{
 536     /**
 537         Assignment operator.
 538     */
 539     wxObjectDataPtr<T>& operator=(const wxObjectDataPtr<T>& tocopy);
 540     wxObjectDataPtr<T>& operator=(T* ptr);
 541     //@}
 542 };
 543
 544
 545
 546 // ============================================================================
 547 // Global functions/macros
 548 // ============================================================================
 549
 550 /** @addtogroup group_funcmacro_rtti */
 551 //@{
 552
 553 /**
 554     Returns a pointer to the wxClassInfo object associated with this class.
 555
 556     @header{wx/object.h}
 557 */
 558 #define CLASSINFO( className )
 559
 560 /**
 561     Used inside a class declaration to declare that the class should be made
 562     known to the class hierarchy, but objects of this class cannot be created
 563     dynamically. The same as DECLARE_ABSTRACT_CLASS().
 564
 565     @header{wx/object.h}
 566 */
 567 #define DECLARE_CLASS( className )
 568
 569 /**
 570     Used inside a class declaration to declare that the class should be
 571     made known to the class hierarchy, but objects of this class cannot be created
 572     dynamically. The same as DECLARE_CLASS().
 573
 574     @header{wx/object.h}
 575
 576     Example:
 577
 578     @code
 579     class wxCommand: public wxObject
 580     {
 581         DECLARE_ABSTRACT_CLASS(wxCommand)
 582
 583     private:
 584         ...
 585     public:
 586         ...
 587     };
 588     @endcode
 589 */
 590 #define DECLARE_ABSTRACT_CLASS( className )
 591
 592 /**
 593     Used inside a class declaration to make the class known to wxWidgets RTTI
 594     system and also declare that the objects of this class should be
 595     dynamically creatable from run-time type information. Notice that this
 596     implies that the class should have a default constructor, if this is not
 597     the case consider using DECLARE_CLASS().
 598
 599     @header{wx/object.h}
 600
 601     Example:
 602
 603     @code
 604     class wxFrame: public wxWindow
 605     {
 606     DECLARE_DYNAMIC_CLASS(wxFrame)
 607
 608     private:
 609         const wxString& frameTitle;
 610     public:
 611         ...
 612     };
 613     @endcode
 614 */
 615 #define DECLARE_DYNAMIC_CLASS( className )
 616
 617 /**
 618     Used in a C++ implementation file to complete the declaration of a class
 619     that has run-time type information. The same as IMPLEMENT_ABSTRACT_CLASS().
 620
 621     @header{wx/object.h}
 622 */
 623 #define IMPLEMENT_CLASS( className, baseClassName )
 624
 625 /**
 626     Used in a C++ implementation file to complete the declaration of a class
 627     that has run-time type information and two base classes. The same as
 628     IMPLEMENT_ABSTRACT_CLASS2().
 629
 630     @header{wx/object.h}
 631 */
 632 #define IMPLEMENT_CLASS2( className, baseClassName1, baseClassName2 )
 633
 634 /**
 635     Used in a C++ implementation file to complete the declaration of a class
 636     that has run-time type information. The same as IMPLEMENT_CLASS().
 637
 638     @header{wx/object.h}
 639
 640     Example:
 641
 642     @code
 643     IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
 644
 645     wxCommand::wxCommand(void)
 646     {
 647         ...
 648     }
 649     @endcode
 650 */
 651 #define IMPLEMENT_ABSTRACT_CLASS( className, baseClassName )
 652
 653 /**
 654     Used in a C++ implementation file to complete the declaration of a class
 655     that has run-time type information and two base classes. The same as
 656     IMPLEMENT_CLASS2().
 657
 658     @header{wx/object.h}
 659 */
 660 #define IMPLEMENT_ABSTRACT_CLASS2( className, baseClassName1, baseClassName2 )
 661
 662 /**
 663     Used in a C++ implementation file to complete the declaration of a class
 664     that has run-time type information, and whose instances can be created
 665     dynamically.
 666
 667     @header{wx/object.h}
 668
 669     Example:
 670
 671     @code
 672     IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
 673
 674     wxFrame::wxFrame(void)
 675     {
 676         ...
 677     }
 678     @endcode
 679 */
 680 #define IMPLEMENT_DYNAMIC_CLASS( className, baseClassName )
 681
 682 /**
 683     Used in a C++ implementation file to complete the declaration of a class
 684     that has run-time type information, and whose instances can be created
 685     dynamically. Use this for classes derived from two base classes.
 686
 687     @header{wx/object.h}
 688 */
 689 #define IMPLEMENT_DYNAMIC_CLASS2( className, baseClassName1, baseClassName2 )
 690
 691 /**
 692     Same as @c const_cast<T>(x) if the compiler supports const cast or @c (T)x for
 693     old compilers. Unlike wxConstCast(), the cast it to the type @c T and not to
 694     <tt>T *</tt> and also the order of arguments is the same as for the standard cast.
 695
 696     @header{wx/defs.h}
 697
 698     @see wx_reinterpret_cast(), wx_static_cast()
 699 */
 700 #define wx_const_cast(T, x)
 701
 702 /**
 703     Same as @c reinterpret_cast<T>(x) if the compiler supports reinterpret cast or
 704     @c (T)x for old compilers.
 705
 706     @header{wx/defs.h}
 707
 708     @see wx_const_cast(), wx_static_cast()
 709 */
 710 #define wx_reinterpret_cast(T, x)
 711
 712 /**
 713     Same as @c static_cast<T>(x) if the compiler supports static cast or @c (T)x for
 714     old compilers. Unlike wxStaticCast(), there are no checks being done and
 715     the meaning of the macro arguments is exactly the same as for the standard
 716     static cast, i.e. @a T is the full type name and star is not appended to it.
 717
 718     @header{wx/defs.h}
 719
 720     @see wx_const_cast(), wx_reinterpret_cast(), wx_truncate_cast()
 721 */
 722 #define wx_static_cast(T, x)
 723
 724 /**
 725     This case doesn’t correspond to any standard cast but exists solely to make
 726     casts which possibly result in a truncation of an integer value more
 727     readable.
 728
 729     @header{wx/defs.h}
 730 */
 731 #define wx_truncate_cast(T, x)
 732
 733 /**
 734     This macro expands into <tt>const_cast<classname *>(ptr)</tt> if the compiler
 735     supports const_cast or into an old, C-style cast, otherwise.
 736
 737     @header{wx/defs.h}
 738
 739     @see wx_const_cast(), wxDynamicCast(), wxStaticCast()
 740 */
 741 #define wxConstCast( ptr, classname )
 742
 743 /**
 744     This macro returns the pointer @e ptr cast to the type @e classname * if
 745     the pointer is of this type (the check is done during the run-time) or
 746     @NULL otherwise. Usage of this macro is preferred over obsoleted
 747     wxObject::IsKindOf() function.
 748
 749     The @e ptr argument may be @NULL, in which case @NULL will be returned.
 750
 751     @header{wx/object.h}
 752
 753     Example:
 754
 755     @code
 756     wxWindow *win = wxWindow::FindFocus();
 757     wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl);
 758     if ( text )
 759     {
 760         // a text control has the focus...
 761     }
 762     else
 763     {
 764         // no window has the focus or it is not a text control
 765     }
 766     @endcode
 767
 768     @see @ref overview_rtti, wxDynamicCastThis(), wxConstCast(), wxStaticCast()
 769 */
 770 #define wxDynamicCast( ptr, classname )
 771
 772 /**
 773     This macro is equivalent to <tt>wxDynamicCast(this, classname)</tt> but the latter provokes
 774     spurious compilation warnings from some compilers (because it tests whether
 775     @c this pointer is non-@NULL which is always true), so this macro should be
 776     used to avoid them.
 777
 778     @header{wx/object.h}
 779
 780     @see wxDynamicCast()
 781 */
 782 #define wxDynamicCastThis( classname )
 783
 784 /**
 785     This macro checks that the cast is valid in debug mode (an assert failure
 786     will result if wxDynamicCast(ptr, classname) == @NULL) and then returns the
 787     result of executing an equivalent of <tt>static_cast<classname *>(ptr)</tt>.
 788
 789     @header{wx/object.h}
 790
 791     @see wx_static_cast(), wxDynamicCast(), wxConstCast()
 792 */
 793 #define wxStaticCast( ptr, classname )
 794
 795 /**
 796     Creates and returns an object of the given class, if the class has been
 797     registered with the dynamic class system using DECLARE... and IMPLEMENT...
 798     macros.
 799
 800     @header{wx/object.h}
 801 */
 802 wxObject *wxCreateDynamicObject(const wxString& className);
 803
 804 //@}
 805
 806 /** @addtogroup group_funcmacro_debug */
 807 //@{
 808
 809 /**
 810     This is defined in debug mode to be call the redefined new operator
 811     with filename and line number arguments. The definition is:
 812
 813     @code
 814     #define WXDEBUG_NEW new(__FILE__,__LINE__)
 815     @endcode
 816
 817     In non-debug mode, this is defined as the normal new operator.
 818
 819     @header{wx/object.h}
 820 */
 821 #define WXDEBUG_NEW( arg )
 822
 823 //@}
 824