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