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 /**
 388     Used inside a class declaration to declare that the class should be
 389     made known to the class hierarchy, but objects of this class cannot be created
 390     dynamically. The same as DECLARE_ABSTRACT_CLASS.
 391 */
 392 #define DECLARE_CLASS()     /* implementation is private */
 393
 394 /**
 395     Used inside a class declaration to declare that the class should be
 396     made known to the class hierarchy, but objects of this class cannot be created
 397     dynamically. The same as DECLARE_CLASS.
 398     Example:
 399
 400     @code
 401     class wxCommand: public wxObject
 402     {
 403       DECLARE_ABSTRACT_CLASS(wxCommand)
 404
 405      private:
 406       ...
 407      public:
 408       ...
 409     };
 410     @endcode
 411 */
 412 #define DECLARE_ABSTRACT_CLASS()     /* implementation is private */
 413
 414 /**
 415     Returns a pointer to the wxClassInfo object associated with this class.
 416 */
 417 #define wxClassInfo* CLASSINFO()     /* implementation is private */
 418
 419 /**
 420     Same as @c reinterpret_castT(x) if the compiler supports reinterpret cast or
 421     @c (T)x for old compilers.
 422
 423     @see wx_const_cast(), wx_static_cast()
 424 */
 425 T wx_reinterpret_cast();
 426
 427 /**
 428     Used in a C++ implementation file to complete the declaration of a
 429     class that has run-time type information and two base classes. The
 430     same as IMPLEMENT_ABSTRACT_CLASS2.
 431 */
 432 #define IMPLEMENT_CLASS2()     /* implementation is private */
 433
 434 /**
 435     This macro expands into @c const_castclassname *(ptr) if the compiler
 436     supports @e const_cast or into an old, C-style cast, otherwise.
 437
 438     @see wx_const_cast(), wxDynamicCast(), wxStaticCast()
 439 */
 440 classname* wxConstCast();
 441
 442 /**
 443     Used in a C++ implementation file to complete the declaration of
 444     a class that has run-time type information. The same as IMPLEMENT_CLASS.
 445     Example:
 446
 447     @code
 448     IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
 449
 450     wxCommand::wxCommand(void)
 451     {
 452     ...
 453     }
 454     @endcode
 455 */
 456 #define IMPLEMENT_ABSTRACT_CLASS()     /* implementation is private */
 457
 458 /**
 459     Used in a C++ implementation file to complete the declaration of
 460     a class that has run-time type information. The same as
 461     IMPLEMENT_ABSTRACT_CLASS.
 462 */
 463 #define IMPLEMENT_CLASS()     /* implementation is private */
 464
 465 /**
 466     This macro is equivalent to @c wxDynamicCast(this, classname) but the
 467     latter provokes spurious compilation warnings from some compilers (because it
 468     tests whether @c this pointer is non-@NULL which is always @true), so
 469     this macro should be used to avoid them.
 470
 471     @see wxDynamicCast()
 472 */
 473 classname* wxDynamicCastThis();
 474
 475 /**
 476     Used in a C++ implementation file to complete the declaration of
 477     a class that has run-time type information, and whose instances
 478     can be created dynamically. Use this for classes derived from two
 479     base classes.
 480 */
 481 #define IMPLEMENT_DYNAMIC_CLASS2()     /* implementation is private */
 482
 483 /**
 484     Creates and returns an object of the given class, if the class has been
 485     registered with the dynamic class system using DECLARE... and IMPLEMENT...
 486     macros.
 487 */
 488 wxObject* wxCreateDynamicObject(const wxString& className);
 489
 490 /**
 491     Used inside a class declaration to make the class known to wxWidgets RTTI
 492     system and also declare that the objects of this class should be dynamically
 493     creatable from run-time type information. Notice that this implies that the
 494     class should have a default constructor, if this is not the case consider using
 495     DECLARE_CLASS().
 496     Example:
 497
 498     @code
 499     class wxFrame: public wxWindow
 500     {
 501       DECLARE_DYNAMIC_CLASS(wxFrame)
 502
 503      private:
 504       const wxString& frameTitle;
 505      public:
 506       ...
 507     };
 508     @endcode
 509 */
 510 #define DECLARE_DYNAMIC_CLASS()     /* implementation is private */
 511
 512 /**
 513     Same as @c const_castT(x) if the compiler supports const cast or
 514     @c (T)x for old compilers. Unlike wxConstCast(),
 515     the cast it to the type @e T and not to @c T * and also the order of
 516     arguments is the same as for the standard cast.
 517
 518     @see wx_reinterpret_cast(), wx_static_cast()
 519 */
 520 T wx_const_cast();
 521
 522 /**
 523     Used in a C++ implementation file to complete the declaration of
 524     a class that has run-time type information and two base classes. The same as
 525     IMPLEMENT_CLASS2.
 526 */
 527 #define IMPLEMENT_ABSTRACT_CLASS2()     /* implementation is private */
 528
 529 /**
 530     This macro returns the pointer @e ptr cast to the type @e classname * if
 531     the pointer is of this type (the check is done during the run-time) or
 532     @NULL otherwise. Usage of this macro is preferred over obsoleted
 533     wxObject::IsKindOf() function.
 534     The @e ptr argument may be @NULL, in which case @NULL will be
 535     returned.
 536     Example:
 537
 538     @code
 539     wxWindow *win = wxWindow::FindFocus();
 540         wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl);
 541         if ( text )
 542         {
 543             // a text control has the focus...
 544         }
 545         else
 546         {
 547             // no window has the focus or it is not a text control
 548         }
 549     @endcode
 550
 551     @see @ref overview_runtimeclassoverview "RTTI overview", wxDynamicCastThis(),
 552          wxConstCast(), wxStaticCast()
 553 */
 554 classname* wxDynamicCast();
 555
 556 /**
 557     This is defined in debug mode to be call the redefined new operator
 558     with filename and line number arguments. The definition is:
 559
 560     @code
 561     #define WXDEBUG_NEW new(__FILE__,__LINE__)
 562     @endcode
 563
 564     In non-debug mode, this is defined as the normal new operator.
 565 */
 566 #define WXDEBUG_NEW()     /* implementation is private */
 567
 568 /**
 569     This macro checks that the cast is valid in debug mode (an assert failure will
 570     result if @c wxDynamicCast(ptr, classname) == @NULL) and then returns the
 571     result of executing an equivalent of @c static_castclassname *(ptr).
 572
 573     @see wx_static_cast(), wxDynamicCast(), wxConstCast()
 574 */
 575 classname* wxStaticCast();
 576
 577 /**
 578     Same as @c static_castT(x) if the compiler supports static cast or
 579     @c (T)x for old compilers. Unlike wxStaticCast(),
 580     there are no checks being done and the meaning of the macro arguments is exactly
 581     the same as for the standard static cast, i.e. @e T is the full type name and
 582     star is not appended to it.
 583
 584     @see wx_const_cast(), wx_reinterpret_cast(), wx_truncate_cast()
 585 */
 586 T wx_static_cast();
 587
 588 /**
 589     Used in a C++ implementation file to complete the declaration of
 590     a class that has run-time type information, and whose instances
 591     can be created dynamically.
 592     Example:
 593
 594     @code
 595     IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
 596
 597     wxFrame::wxFrame(void)
 598     {
 599     ...
 600     }
 601     @endcode
 602 */
 603 #define IMPLEMENT_DYNAMIC_CLASS()     /* implementation is private */
 604