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         Please note that after calling this function, the caller should absolutely
  44         avoid to use
  45         the pointer to this instance since it may not be valid anymore.
  46     */
  47     void DecRef();
  48
  49     /**
  50         Returns the reference count associated with this shared data.
  51         When this goes to zero during a DecRef() call, the object
  52         will auto-free itself.
  53     */
  54     int GetRefCount();
  55
  56     /**
  57         Increments the reference count associated with this shared data.
  58     */
  59     void IncRef();
  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     @seealso
  87     wxClassInfo, @ref overview_debuggingoverview, wxObjectRefData
  88 */
  89 class wxObject
  90 {
  91 public:
  92     //@{
  93     /**
  94         Default and copy constructors.
  95     */
  96     wxObject();
  97     wxObject(const wxObject& other);
  98     //@}
  99
 100     /**
 101         Destructor. Performs dereferencing, for those objects
 102         that use reference counting.
 103     */
 104     wxObject();
 105
 106     /**
 107         A virtual function that may be redefined by derived classes to allow dumping of
 108         memory states.
 109         This function is only defined in debug build and doesn't exist at all if
 110         @c __WXDEBUG__ is not defined.
 111
 112         @param stream
 113             Stream on which to output dump information.
 114
 115         @remarks Currently wxWidgets does not define Dump for derived classes,
 116                  but programmers may wish to use it for their own
 117                  applications. Be sure to call the Dump member of the
 118                  class's base class to allow all information to be
 119                  dumped.
 120     */
 121     void Dump(ostream& stream);
 122
 123     /**
 124         This virtual function is redefined for every class that requires run-time
 125         type information, when using DECLARE_CLASS macros.
 126     */
 127     wxClassInfo* GetClassInfo();
 128
 129     /**
 130         Returns the @b m_refData pointer.
 131
 132         @see Ref(), UnRef(), wxObject::m_refData, SetRefData(),
 133              wxObjectRefData
 134     */
 135     wxObjectRefData* GetRefData();
 136
 137     /**
 138         Determines whether this class is a subclass of (or the same class as)
 139         the given class.
 140
 141         @param info
 142             A pointer to a class information object, which may be obtained
 143             by using the CLASSINFO macro.
 144
 145         @returns @true if the class represented by info is the same class as this
 146                  one or is derived from it.
 147     */
 148     bool IsKindOf(wxClassInfo* info);
 149
 150     /**
 151         Returns @true if this object has the same data pointer as @e obj. Notice
 152         that @true is returned if the data pointers are @NULL in both objects.
 153         This function only does a shallow comparison, i.e. it doesn't compare
 154         the objects pointed to by the data pointers of these objects.
 155     */
 156     bool IsSameAs(const wxObject& obj);
 157
 158     /**
 159         Makes this object refer to the data in @e clone.
 160
 161         @param clone
 162             The object to 'clone'.
 163
 164         @remarks First this function calls UnRef() on itself to decrement
 165                  (and perhaps free) the data it is currently referring
 166                  to.
 167
 168         @see UnRef(), wxObject::m_refData, SetRefData(),
 169              GetRefData(), wxObjectRefData
 170     */
 171     void Ref(const wxObject& clone);
 172
 173     /**
 174         Sets the @b m_refData pointer.
 175
 176         @see Ref(), UnRef(), wxObject::m_refData, GetRefData(),
 177              wxObjectRefData
 178     */
 179     void SetRefData(wxObjectRefData* data);
 180
 181     /**
 182         Decrements the reference count in the associated data, and if it is zero,
 183         deletes the data.
 184         The @b m_refData member is set to @NULL.
 185
 186         @see Ref(), wxObject::m_refData, SetRefData(),
 187              GetRefData(), wxObjectRefData
 188     */
 189     void UnRef();
 190
 191     /**
 192         Ensure that this object's data is not shared with any other object.
 193         if we have no
 194         data, it is created using CreateRefData() below, if we have shared data
 195         it is copied using CloneRefData(), otherwise nothing is done.
 196     */
 197     void UnShare();
 198
 199     /**
 200         wxObjectRefData*  m_refData
 201         Pointer to an object which is the object's reference-counted data.
 202
 203         @see Ref(), UnRef(), SetRefData(),
 204              GetRefData(), wxObjectRefData
 205     */
 206
 207
 208     /**
 209         The @e delete operator is defined for debugging versions of the library only,
 210         when
 211         the identifier __WXDEBUG__ is defined. It takes over memory deallocation,
 212         allowing
 213         wxDebugContext operations.
 214     */
 215     void delete(void buf);
 216
 217     /**
 218         The @e new operator is defined for debugging versions of the library only, when
 219         the identifier __WXDEBUG__ is defined. It takes over memory allocation, allowing
 220         wxDebugContext operations.
 221     */
 222     void* new(size_t size, const wxString& filename = NULL,
 223               int lineNum = 0);
 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     @seealso
 239     Overview, wxObject
 240 */
 241 class wxClassInfo
 242 {
 243 public:
 244     /**
 245         Constructs a wxClassInfo object. The supplied macros implicitly construct
 246         objects of this
 247         class, so there is no need to create such objects explicitly in an application.
 248     */
 249     wxClassInfo(const wxChar* className,
 250                 const wxClassInfo* baseClass1,
 251                 const wxClassInfo* baseClass2,
 252                 int size, wxObjectConstructorFn fn);
 253
 254     /**
 255         Creates an object of the appropriate kind. Returns @NULL if the class has not
 256         been declared
 257         dynamically creatable (typically, it is an abstract class).
 258     */
 259     wxObject* CreateObject();
 260
 261     /**
 262         Finds the wxClassInfo object for a class of the given string name.
 263     */
 264     static wxClassInfo* FindClass(wxChar* name);
 265
 266     /**
 267         Returns the name of the first base class (@NULL if none).
 268     */
 269     wxChar* GetBaseClassName1();
 270
 271     /**
 272         Returns the name of the second base class (@NULL if none).
 273     */
 274     wxChar* GetBaseClassName2();
 275
 276     /**
 277         Returns the string form of the class name.
 278     */
 279     wxChar* GetClassName();
 280
 281     /**
 282         Returns the size of the class.
 283     */
 284     int GetSize();
 285
 286     /**
 287         Initializes pointers in the wxClassInfo objects for fast execution
 288         of IsKindOf. Called in base wxWidgets library initialization.
 289     */
 290     static void InitializeClasses();
 291
 292     /**
 293         Returns @true if this class info can create objects of the associated class.
 294     */
 295     bool IsDynamic();
 296
 297     /**
 298         Returns @true if this class is a kind of (inherits from) the given class.
 299     */
 300     bool IsKindOf(wxClassInfo* info);
 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     @seealso
 325     wxObject, wxObjectRefData, @ref overview_trefcount "Reference counting"
 326 */
 327 class wxObjectDataPtr<T>
 328 {
 329 public:
 330     //@{
 331     /**
 332         This copy constructor increases the count of the reference
 333         counted object to which @a tocopy points and then this
 334         class will point to, as well.
 335     */
 336     wxObjectDataPtrT(T* ptr = NULL);
 337     wxObjectDataPtrT(const wxObjectDataPtr<T>& tocopy);
 338     //@}
 339
 340     /**
 341         Decreases the reference count of the object to which this
 342         class points.
 343     */
 344     ~wxObjectDataPtrT();
 345
 346     /**
 347         Gets a pointer to the reference counted object to which
 348         this class points.
 349     */
 350     T* get();
 351
 352     /**
 353         Conversion to a boolean expression (in a variant which is not
 354         convertable to anything but a boolean expression). If this class
 355         contains a valid pointer it will return @e @true, if it contains
 356         a @NULL pointer it will return @e @false.
 357     */
 358     operator unspecified_bool_type();
 359
 360     /**
 361         Returns a reference to the object. If the internal pointer is @NULL
 362         this method will cause an assert in debug mode.
 363     */
 364     T operator*();
 365
 366     /**
 367         Returns a pointer to the reference counted object to which
 368         this class points. If this the internal pointer is @NULL,
 369         this method will assert in debug mode.
 370     */
 371     T* operator-();
 372
 373     //@{
 374     /**
 375         Assignment operators.
 376     */
 377     wxObjectDataPtrT& operator operator=(const wxObjectDataPtr<T>& tocopy);
 378     wxObjectDataPtrT& operator operator=(T* ptr);
 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