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     @class wxObjectDataPtrT
 306     @wxheader{object.h}
 307
 308     This is helper template class primarily written to avoid memory
 309     leaks because of missing calls to wxObjectRefData::DecRef.
 310
 311     Despite the name this template can actually be used as a
 312     smart pointer for any class implementing the reference
 313     counting interface which only consists of the two methods
 314     @b T::IncRef() and @b T::DecRef().
 315
 316     The difference to wxSharedPtr is that
 317     wxObjectDataPtr relies on the reference counting to be in
 318     the class pointed to where as wxSharedPtr implements the
 319     reference counting itself.
 320
 321     @library{wxbase}
 322     @category{FIXME}
 323
 324     @see wxObject, wxObjectRefData, @ref overview_trefcount "Reference counting"
 325 */
 326 class wxObjectDataPtr<T>
 327 {
 328 public:
 329     //@{
 330     /**
 331         This copy constructor increases the count of the reference
 332         counted object to which @a tocopy points and then this
 333         class will point to, as well.
 334     */
 335     wxObjectDataPtrT(T* ptr = NULL);
 336     wxObjectDataPtrT(const wxObjectDataPtr<T>& tocopy);
 337     //@}
 338
 339     /**
 340         Decreases the reference count of the object to which this
 341         class points.
 342     */
 343     ~wxObjectDataPtrT();
 344
 345     /**
 346         Gets a pointer to the reference counted object to which
 347         this class points.
 348     */
 349     T* get() const;
 350
 351     /**
 352         Conversion to a boolean expression (in a variant which is not
 353         convertable to anything but a boolean expression). If this class
 354         contains a valid pointer it will return @e @true, if it contains
 355         a @NULL pointer it will return @e @false.
 356     */
 357     operator unspecified_bool_type() const;
 358
 359     /**
 360         Returns a reference to the object. If the internal pointer is @NULL
 361         this method will cause an assert in debug mode.
 362     */
 363     T operator*() const;
 364
 365     /**
 366         Returns a pointer to the reference counted object to which
 367         this class points. If this the internal pointer is @NULL,
 368         this method will assert in debug mode.
 369     */
 370     T* operator-() const;
 371
 372     //@{
 373     /**
 374         Assignment operators.
 375     */
 376     wxObjectDataPtrT& operator operator=(const wxObjectDataPtr<T>& tocopy);
 377     wxObjectDataPtrT& operator operator=(T* ptr);
 378     //@}
 379 };
 380
 381
 382
 383 // ============================================================================
 384 // Global functions/macros
 385 // ============================================================================
 386
 387 /** @ingroup group_funcmacro_rtti */
 388 //@{
 389
 390 /**
 391     Returns a pointer to the wxClassInfo object associated with this class.
 392
 393     @header{wx/object.h}
 394 */
 395 #define CLASSINFO( className )
 396
 397 /**
 398     Used inside a class declaration to declare that the class should be made
 399     known to the class hierarchy, but objects of this class cannot be created
 400     dynamically. The same as DECLARE_ABSTRACT_CLASS().
 401
 402     @header{wx/object.h}
 403 */
 404 #define DECLARE_CLASS( className )
 405
 406 /**
 407     Used inside a class declaration to declare that the class should be
 408     made known to the class hierarchy, but objects of this class cannot be created
 409     dynamically. The same as DECLARE_CLASS().
 410
 411     @header{wx/object.h}
 412
 413     Example:
 414
 415     @code
 416     class wxCommand: public wxObject
 417     {
 418         DECLARE_ABSTRACT_CLASS(wxCommand)
 419
 420     private:
 421         ...
 422     public:
 423         ...
 424     };
 425     @endcode
 426 */
 427 #define DECLARE_ABSTRACT_CLASS( className )
 428
 429 /**
 430     Used inside a class declaration to make the class known to wxWidgets RTTI
 431     system and also declare that the objects of this class should be
 432     dynamically creatable from run-time type information. Notice that this
 433     implies that the class should have a default constructor, if this is not
 434     the case consider using DECLARE_CLASS().
 435
 436     @header{wx/object.h}
 437
 438     Example:
 439
 440     @code
 441     class wxFrame: public wxWindow
 442     {
 443     DECLARE_DYNAMIC_CLASS(wxFrame)
 444
 445     private:
 446         const wxString& frameTitle;
 447     public:
 448         ...
 449     };
 450     @endcode
 451 */
 452 #define DECLARE_DYNAMIC_CLASS( className )
 453
 454 /**
 455     Used in a C++ implementation file to complete the declaration of a class
 456     that has run-time type information. The same as IMPLEMENT_ABSTRACT_CLASS().
 457
 458     @header{wx/object.h}
 459 */
 460 #define IMPLEMENT_CLASS( className, baseClassName )
 461
 462 /**
 463     Used in a C++ implementation file to complete the declaration of a class
 464     that has run-time type information and two base classes. The same as
 465     IMPLEMENT_ABSTRACT_CLASS2().
 466
 467     @header{wx/object.h}
 468 */
 469 #define IMPLEMENT_CLASS2( className, baseClassName1, baseClassName2 )
 470
 471 /**
 472     Used in a C++ implementation file to complete the declaration of a class
 473     that has run-time type information. The same as IMPLEMENT_CLASS().
 474
 475     @header{wx/object.h}
 476
 477     Example:
 478
 479     @code
 480     IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
 481
 482     wxCommand::wxCommand(void)
 483     {
 484         ...
 485     }
 486     @endcode
 487 */
 488 #define IMPLEMENT_ABSTRACT_CLASS( className, baseClassName )
 489
 490 /**
 491     Used in a C++ implementation file to complete the declaration of a class
 492     that has run-time type information and two base classes. The same as
 493     IMPLEMENT_CLASS2().
 494
 495     @header{wx/object.h}
 496 */
 497 #define IMPLEMENT_ABSTRACT_CLASS2( className, baseClassName1, baseClassName2 )
 498
 499 /**
 500     Used in a C++ implementation file to complete the declaration of a class
 501     that has run-time type information, and whose instances can be created
 502     dynamically.
 503
 504     @header{wx/object.h}
 505
 506     Example:
 507
 508     @code
 509     IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
 510
 511     wxFrame::wxFrame(void)
 512     {
 513         ...
 514     }
 515     @endcode
 516 */
 517 #define IMPLEMENT_DYNAMIC_CLASS( className, baseClassName )
 518
 519 /**
 520     Used in a C++ implementation file to complete the declaration of a class
 521     that has run-time type information, and whose instances can be created
 522     dynamically. Use this for classes derived from two base classes.
 523
 524     @header{wx/object.h}
 525 */
 526 #define IMPLEMENT_DYNAMIC_CLASS2( className, baseClassName1, baseClassName2 )
 527
 528 /**
 529     Same as const_cast<T>(x) if the compiler supports const cast or (T)x for
 530     old compilers. Unlike wxConstCast(), the cast it to the type T and not to
 531     T * and also the order of arguments is the same as for the standard cast.
 532
 533     @header{wx/defs.h}
 534
 535     @see wx_reinterpret_cast(), wx_static_cast()
 536 */
 537 #define wx_const_cast(T, x)
 538
 539 /**
 540     Same as reinterpret_cast<T>(x) if the compiler supports reinterpret cast or
 541     (T)x for old compilers.
 542
 543     @header{wx/defs.h}
 544
 545     @see wx_const_cast(), wx_static_cast()
 546 */
 547 #define wx_reinterpret_cast(T, x)
 548
 549 /**
 550     Same as static_cast<T>(x) if the compiler supports static cast or (T)x for
 551     old compilers. Unlike wxStaticCast(), there are no checks being done and
 552     the meaning of the macro arguments is exactly the same as for the standard
 553     static cast, i.e. T is the full type name and star is not appended to it.
 554
 555     @header{wx/defs.h}
 556
 557     @see wx_const_cast(), wx_reinterpret_cast(), wx_truncate_cast()
 558 */
 559 #define wx_static_cast(T, x)
 560
 561 /**
 562     This case doesn’t correspond to any standard cast but exists solely to make
 563     casts which possibly result in a truncation of an integer value more
 564     readable.
 565
 566     @header{wx/defs.h}
 567 */
 568 #define wx_truncate_cast(T, x)
 569
 570 /**
 571     This macro expands into const_cast<classname *>(ptr) if the compiler
 572     supports const_cast or into an old, C-style cast, otherwise.
 573
 574     @header{wx/defs.h}
 575
 576     @see wx_const_cast(), wxDynamicCast(), wxStaticCast()
 577 */
 578 #define wxConstCast( ptr, classname )
 579
 580 /**
 581     This is defined in debug mode to be call the redefined new operator
 582     with filename and line number arguments. The definition is:
 583
 584     @code
 585     #define WXDEBUG_NEW new(__FILE__,__LINE__)
 586     @endcode
 587
 588     In non-debug mode, this is defined as the normal new operator.
 589
 590     @header{wx/object.h}
 591 */
 592 #define WXDEBUG_NEW( arg )
 593
 594 /**
 595     This macro returns the pointer @e ptr cast to the type @e classname * if
 596     the pointer is of this type (the check is done during the run-time) or
 597     @NULL otherwise. Usage of this macro is preferred over obsoleted
 598     wxObject::IsKindOf() function.
 599
 600     The @e ptr argument may be @NULL, in which case @NULL will be returned.
 601
 602     @header{wx/object.h}
 603
 604     Example:
 605
 606     @code
 607     wxWindow *win = wxWindow::FindFocus();
 608     wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl);
 609     if ( text )
 610     {
 611         // a text control has the focus...
 612     }
 613     else
 614     {
 615         // no window has the focus or it is not a text control
 616     }
 617     @endcode
 618
 619     @see @ref overview_runtimeclassoverview "RTTI Overview",
 620          wxDynamicCastThis(), wxConstCast(), wxStaticCast()
 621 */
 622 #define wxDynamicCast( ptr, classname )
 623
 624 /**
 625     This macro is equivalent to wxDynamicCast() but the latter provokes
 626     spurious compilation warnings from some compilers (because it tests whether
 627     @c this pointer is non-@NULL which is always true), so this macro should be
 628     used to avoid them.
 629
 630     @header{wx/object.h}
 631
 632     @see wxDynamicCast()
 633 */
 634 #define wxDynamicCastThis( classname )
 635
 636 /**
 637     This macro checks that the cast is valid in debug mode (an assert failure
 638     will result if wxDynamicCast(ptr, classname) == @NULL) and then returns the
 639     result of executing an equivalent of static_cast<classname *>(ptr).
 640
 641     @header{wx/object.h}
 642
 643     @see wx_static_cast(), wxDynamicCast(), wxConstCast()
 644 */
 645 #define wxStaticCast( ptr, classname )
 646
 647 /**
 648     Creates and returns an object of the given class, if the class has been
 649     registered with the dynamic class system using DECLARE... and IMPLEMENT...
 650     macros.
 651
 652     @header{wx/object.h}
 653 */
 654 wxObject *wxCreateDynamicObject(const wxString& className);
 655
 656 //@}
 657