interface/object.h

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