X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b1db61e1fd85b9d28702fb613dba5f375108ff5d..7c0d297a1f761de31d3a4ac924fa2080b5bbaf41:/interface/object.h diff --git a/interface/object.h b/interface/object.h index b8795b34a7..e84f3a8266 100644 --- a/interface/object.h +++ b/interface/object.h @@ -10,45 +10,145 @@ @class wxObjectRefData @wxheader{object.h} - This class is used to store reference-counted data. Derive classes from this to - store your own data. When retrieving information from a @b wxObject's reference - data, - you will need to cast to your own derived class. + This class is used to store reference-counted data. + + Derive classes from this to store your own data. When retrieving information + from a wxObject's reference data, you will need to cast to your own derived class. + + @b Example: + + @code + // include file + + class MyCar: public wxObject + { + public: + MyCar() { } + MyCar( int price ); + + bool IsOk() const { return m_refData != NULL; } + + bool operator == ( const MyCar& car ) const; + bool operator != (const MyCar& car) const { return !(*this == car); } + + void SetPrice( int price ); + int GetPrice() const; + + protected: + virtual wxObjectRefData *CreateRefData() const; + virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const; + + DECLARE_DYNAMIC_CLASS(MyCar) + }; + + + // implementation + + class MyCarRefData: public wxObjectRefData + { + public: + MyCarRefData() + { + m_price = 0; + } + + MyCarRefData( const MyCarRefData& data ) + : wxObjectRefData() + { + m_price = data.m_price; + } + + bool operator == (const MyCarRefData& data) const + { + return m_price == data.m_price; + } + + int m_price; + }; + + + #define M_CARDATA ((MyCarRefData *)m_refData) + + IMPLEMENT_DYNAMIC_CLASS(MyCar,wxObject) + + MyCar::MyCar( int price ) + { + m_refData = new MyCarRefData(); + M_CARDATA->m_price = price; + } + + wxObjectRefData *MyCar::CreateRefData() const + { + return new MyCarRefData; + } + + wxObjectRefData *MyCar::CloneRefData(const wxObjectRefData *data) const + { + return new MyCarRefData(*(MyCarRefData *)data); + } + + bool MyCar::operator == ( const MyCar& car ) const + { + if (m_refData == car.m_refData) return true; + + if (!m_refData || !car.m_refData) return false; + + return ( *(MyCarRefData*)m_refData == *(MyCarRefData*)car.m_refData ); + } + + void MyCar::SetPrice( int price ) + { + UnShare(); + + M_CARDATA->m_price = price; + } + + int MyCar::GetPrice() const + { + wxCHECK_MSG( IsOk(), -1, "invalid car" ); + + return (M_CARDATA->m_price); + } + @endcode + @library{wxbase} - @category{FIXME} + @category{rtti} - @see wxObject, wxObjectDataPtrT(), @ref overview_trefcount "Reference counting" + @see wxObject, wxObjectDataPtr, @ref overview_refcount */ class wxObjectRefData { -public: +protected: /** - Default constructor. Initialises the internal reference count to 1. + Destructor. + + It's declared @c protected so that wxObjectRefData instances + will never be destroyed directly but only as result of a DecRef() call. */ - wxObjectRefData(); + ~wxObjectRefData(); +public: /** - Destructor. It's declared @c protected so that wxObjectRefData instances will - never - be destroyed directly but only as result of a DecRef() call. + Default constructor. Initialises the internal reference count to 1. */ wxObjectRefData(); /** - Decrements the reference count associated with this shared data and, if it - reaches zero, - destroys this instance of wxObjectRefData releasing its memory. - Please note that after calling this function, the caller should absolutely - avoid to use - the pointer to this instance since it may not be valid anymore. + Decrements the reference count associated with this shared data and, if + it reaches zero, destroys this instance of wxObjectRefData releasing its + memory. + + Please note that after calling this function, the caller should + absolutely avoid to use the pointer to this instance since it may not be + valid anymore. */ void DecRef(); /** Returns the reference count associated with this shared data. - When this goes to zero during a DecRef() call, the object - will auto-free itself. + + When this goes to zero during a DecRef() call, the object will auto-free itself. */ int GetRefCount() const; @@ -65,71 +165,74 @@ public: @wxheader{object.h} This is the root class of many of the wxWidgets classes. - It declares a virtual destructor which ensures that - destructors get called for all derived class objects where necessary. - wxObject is the hub of a dynamic object creation - scheme, enabling a program to create instances of a class only knowing - its string class name, and to query the class hierarchy. + It declares a virtual destructor which ensures that destructors get called + for all derived class objects where necessary. - The class contains optional debugging versions - of @b new and @b delete, which can help trace memory allocation - and deallocation problems. + wxObject is the hub of a dynamic object creation scheme, enabling a program + to create instances of a class only knowing its string class name, and to + query the class hierarchy. - wxObject can be used to implement @ref overview_trefcount "reference counted" - objects, - such as wxPen, wxBitmap and others (see @ref overview_refcountlist "this list"). + The class contains optional debugging versions of @b new and @b delete, which + can help trace memory allocation and deallocation problems. + + wxObject can be used to implement @ref overview_refcount "reference counted" + objects, such as wxPen, wxBitmap and others + (see @ref overview_refcount_list "this list"). @library{wxbase} @category{rtti} - @see wxClassInfo, @ref overview_debuggingoverview, wxObjectRefData + @see wxClassInfo, @ref overview_debugging, wxObjectRefData */ class wxObject { public: - //@{ + + wxObject(); + /** - Default and copy constructors. + Copy ctor. */ - wxObject(); wxObject(const wxObject& other); - //@} + /** - Destructor. Performs dereferencing, for those objects - that use reference counting. + Destructor. + + Performs dereferencing, for those objects that use reference counting. */ wxObject(); /** A virtual function that may be redefined by derived classes to allow dumping of memory states. - This function is only defined in debug build and doesn't exist at all if - @c __WXDEBUG__ is not defined. + + This function is only defined in debug build and exists only if @c __WXDEBUG__ + is defined. @param stream Stream on which to output dump information. - @remarks Currently wxWidgets does not define Dump for derived classes, - but programmers may wish to use it for their own - applications. Be sure to call the Dump member of the - class's base class to allow all information to be - dumped. + @remarks Currently wxWidgets does not define Dump() for derived classes, + but programmers may wish to use it for their own applications. + Be sure to call the Dump member of the class's base class to allow all + information to be dumped. + The implementation of this function in wxObject just writes + the class name of the object. */ void Dump(ostream& stream); /** This virtual function is redefined for every class that requires run-time - type information, when using DECLARE_CLASS macros. + type information, when using the ::DECLARE_CLASS macro (or similar). */ wxClassInfo* GetClassInfo(); /** - Returns the @b m_refData pointer. + Returns the wxObject::m_refData pointer, i.e. the data referenced by this object. - @see Ref(), UnRef(), wxObject::m_refData, SetRefData(), - wxObjectRefData + @see Ref(), UnRef(), wxObject::m_refData, SetRefData(), wxObjectRefData */ wxObjectRefData* GetRefData() const; @@ -137,9 +240,15 @@ public: Determines whether this class is a subclass of (or the same class as) the given class. + Example: + + @code + bool tmp = obj->IsKindOf(CLASSINFO(wxFrame)); + @endcode + @param info A pointer to a class information object, which may be obtained - by using the CLASSINFO macro. + by using the ::CLASSINFO macro. @returns @true if the class represented by info is the same class as this one or is derived from it. @@ -147,79 +256,82 @@ public: bool IsKindOf(wxClassInfo* info); /** - Returns @true if this object has the same data pointer as @e obj. Notice - that @true is returned if the data pointers are @NULL in both objects. - This function only does a shallow comparison, i.e. it doesn't compare + Returns @true if this object has the same data pointer as @a obj. + + Notice that @true is returned if the data pointers are @NULL in both objects. + + This function only does a @e shallow comparison, i.e. it doesn't compare the objects pointed to by the data pointers of these objects. + + @see @ref overview_refcount */ bool IsSameAs(const wxObject& obj); /** - Makes this object refer to the data in @e clone. + Makes this object refer to the data in @a clone. @param clone The object to 'clone'. @remarks First this function calls UnRef() on itself to decrement - (and perhaps free) the data it is currently referring - to. + (and perhaps free) the data it is currently referring to. + It then sets its own wxObject::m_refData to point to that of @a clone, + and increments the reference count inside the data. - @see UnRef(), wxObject::m_refData, SetRefData(), - GetRefData(), wxObjectRefData + @see UnRef(), SetRefData(), GetRefData(), wxObjectRefData */ void Ref(const wxObject& clone); /** - Sets the @b m_refData pointer. + Sets the wxObject::m_refData pointer. - @see Ref(), UnRef(), wxObject::m_refData, GetRefData(), - wxObjectRefData + @see Ref(), UnRef(), GetRefData(), wxObjectRefData */ void SetRefData(wxObjectRefData* data); /** Decrements the reference count in the associated data, and if it is zero, deletes the data. - The @b m_refData member is set to @NULL. - @see Ref(), wxObject::m_refData, SetRefData(), - GetRefData(), wxObjectRefData + The wxObject::m_refData member is set to @NULL. + + @see Ref(), SetRefData(), GetRefData(), wxObjectRefData */ void UnRef(); /** Ensure that this object's data is not shared with any other object. - if we have no - data, it is created using CreateRefData() below, if we have shared data - it is copied using CloneRefData(), otherwise nothing is done. + + If we have no data, it is created using CreateRefData() below, + if we have shared data, it is copied using CloneRefData(), + otherwise nothing is done. */ void UnShare(); /** - wxObjectRefData* m_refData - Pointer to an object which is the object's reference-counted data. + The @e delete operator is defined for debugging versions of the library only, + when the identifier @c __WXDEBUG__ is defined. - @see Ref(), UnRef(), SetRefData(), - GetRefData(), wxObjectRefData + It takes over memory deallocation, allowing wxDebugContext operations. */ - + void operator delete(void *buf); /** - The @e delete operator is defined for debugging versions of the library only, - when - the identifier __WXDEBUG__ is defined. It takes over memory deallocation, - allowing - wxDebugContext operations. + The @e new operator is defined for debugging versions of the library only, when + the identifier @c __WXDEBUG__ is defined. + + It takes over memory allocation, allowing wxDebugContext operations. */ - void delete(void buf); + void* operator new(size_t size, const wxString& filename = NULL, int lineNum = 0); + +protected: /** - The @e new operator is defined for debugging versions of the library only, when - the identifier __WXDEBUG__ is defined. It takes over memory allocation, allowing - wxDebugContext operations. + Pointer to an object which is the object's reference-counted data. + + @see Ref(), UnRef(), SetRefData(), GetRefData(), wxObjectRefData */ - void* new(size_t size, const wxString& filename = NULL, - int lineNum = 0); + wxObjectRefData* m_refData; }; @@ -228,22 +340,25 @@ public: @class wxClassInfo @wxheader{object.h} - This class stores meta-information about classes. Instances of this class are - not generally defined directly by an application, but indirectly through use - of macros such as @b DECLARE_DYNAMIC_CLASS and @b IMPLEMENT_DYNAMIC_CLASS. + This class stores meta-information about classes. + + Instances of this class are not generally defined directly by an application, + but indirectly through use of macros such as ::DECLARE_DYNAMIC_CLASS and + ::IMPLEMENT_DYNAMIC_CLASS. @library{wxbase} @category{rtti} - @see Overview(), wxObject + @see @ref overview_rtti_classinfo, wxObject */ class wxClassInfo { public: /** - Constructs a wxClassInfo object. The supplied macros implicitly construct - objects of this - class, so there is no need to create such objects explicitly in an application. + Constructs a wxClassInfo object. + + The supplied macros implicitly construct objects of this class, so there is no + need to create such objects explicitly in an application. */ wxClassInfo(const wxChar* className, const wxClassInfo* baseClass1, @@ -251,14 +366,15 @@ public: int size, wxObjectConstructorFn fn); /** - Creates an object of the appropriate kind. Returns @NULL if the class has not - been declared - dynamically creatable (typically, it is an abstract class). + Creates an object of the appropriate kind. + + @returns @NULL if the class has not been declared dynamically creatable + (typically, this happens for abstract classes). */ wxObject* CreateObject() const; /** - Finds the wxClassInfo object for a class of the given string name. + Finds the wxClassInfo object for a class with the given @a name. */ static wxClassInfo* FindClass(wxChar* name); @@ -283,8 +399,8 @@ public: int GetSize() const; /** - Initializes pointers in the wxClassInfo objects for fast execution - of IsKindOf. Called in base wxWidgets library initialization. + Initializes pointers in the wxClassInfo objects for fast execution of IsKindOf(). + Called in base wxWidgets library initialization. */ static void InitializeClasses(); @@ -304,76 +420,153 @@ public: /** @wxheader{object.h} - This is helper template class primarily written to avoid memory - leaks because of missing calls to wxObjectRefData::DecRef. + This is helper template class primarily written to avoid memory leaks because of + missing calls to wxObjectRefData::DecRef(). - Despite the name this template can actually be used as a - smart pointer for any class implementing the reference - counting interface which only consists of the two methods - @b T::IncRef() and @b T::DecRef(). + Despite the name this template can actually be used as a smart pointer for any + class implementing the reference counting interface which only consists of the two + methods @b T::IncRef() and @b T::DecRef(). - The difference to wxSharedPtr is that - wxObjectDataPtr relies on the reference counting to be in - the class pointed to where as wxSharedPtr implements the + The difference to wxSharedPtr is that wxObjectDataPtr relies on the reference + counting to be in the class pointed to where instead wxSharedPtr implements the reference counting itself. + + @b Example: + + @code + class MyCarRefData: public wxObjectRefData + { + public: + MyCarRefData() { m_price = 0; } + + MyCarRefData( const MyCarRefData& data ) + : wxObjectRefData() + { + m_price = data.m_price; + } + + void SetPrice( int price ) { m_price = price; } + int GetPrice() { return m_price; } + + protected: + int m_price; + }; + + class MyCar + { + public: + MyCar( int price ) : m_data( new MyCarRefData ) + { + m_data->SetPrice( price ); + } + + MyCar& operator =( const MyCar& tocopy ) + { + m_data = tocopy.m_data; + return *this; + } + + bool operator == ( const MyCar& other ) const + { + if (m_data.get() == other.m_data.get()) return true; + return (m_data->GetPrice() == other.m_data->GetPrice()); + } + + void SetPrice( int price ) + { + UnShare(); + m_data->SetPrice( price ); + } + + int GetPrice() const + { + return m_data->GetPrice(); + } + + wxObjectDataPtr m_data; + + protected: + void UnShare() + { + if (m_data->GetRefCount() == 1) + return; + + m_data.reset( new MyCarRefData( *m_data ) ); + } + }; + @endcode + + @library{wxbase} - @category{FIXME} + @category{rtti,smartpointers} - @see wxObject, wxObjectRefData, @ref overview_trefcount "Reference counting" + @see wxObject, wxObjectRefData, @ref overview_refcount, wxSharedPtr, + wxScopedPtr, wxWeakRef */ class wxObjectDataPtr { public: - //@{ /** - This copy constructor increases the count of the reference - counted object to which @a tocopy points and then this - class will point to, as well. + Constructor. + + @a ptr is a pointer to the reference counted object to which this class points. + If @a ptr is not NULL @b T::IncRef() will be called on the object. */ - wxObjectDataPtrT(T* ptr = NULL); - wxObjectDataPtrT(const wxObjectDataPtr& tocopy); - //@} + wxObjectDataPtr(T* ptr = NULL); /** - Decreases the reference count of the object to which this - class points. + This copy constructor increases the count of the reference counted object to + which @a tocopy points and then this class will point to, as well. */ - ~wxObjectDataPtrT(); + wxObjectDataPtr(const wxObjectDataPtr& tocopy); + /** - Gets a pointer to the reference counted object to which - this class points. + Decreases the reference count of the object to which this class points. + */ + ~wxObjectDataPtr(); + + /** + Gets a pointer to the reference counted object to which this class points. */ T* get() const; + /** + Reset this class to ptr which points to a reference counted object and + calls T::DecRef() on the previously owned object. + */ + void reset(T *ptr) + /** Conversion to a boolean expression (in a variant which is not - convertable to anything but a boolean expression). If this class - contains a valid pointer it will return @e @true, if it contains - a @NULL pointer it will return @e @false. + convertable to anything but a boolean expression). + + If this class contains a valid pointer it will return @true, if it contains + a @NULL pointer it will return @false. */ operator unspecified_bool_type() const; /** - Returns a reference to the object. If the internal pointer is @NULL - this method will cause an assert in debug mode. + Returns a reference to the object. + + If the internal pointer is @NULL this method will cause an assert in debug mode. */ - T operator*() const; + T& operator*() const; /** - Returns a pointer to the reference counted object to which - this class points. If this the internal pointer is @NULL, - this method will assert in debug mode. + Returns a pointer to the reference counted object to which this class points. + + If this the internal pointer is @NULL, this method will assert in debug mode. */ - T* operator-() const; + T* operator->() const; //@{ /** - Assignment operators. + Assignment operator. */ - wxObjectDataPtrT& operator operator=(const wxObjectDataPtr& tocopy); - wxObjectDataPtrT& operator operator=(T* ptr); + wxObjectDataPtr& operator=(const wxObjectDataPtr& tocopy); + wxObjectDataPtr& operator=(T* ptr); //@} }; @@ -525,9 +718,9 @@ public: #define IMPLEMENT_DYNAMIC_CLASS2( className, baseClassName1, baseClassName2 ) /** - Same as const_cast(x) if the compiler supports const cast or (T)x for - old compilers. Unlike wxConstCast(), the cast it to the type T and not to - T * and also the order of arguments is the same as for the standard cast. + Same as @c const_cast(x) if the compiler supports const cast or @c (T)x for + old compilers. Unlike wxConstCast(), the cast it to the type @c T and not to + T * and also the order of arguments is the same as for the standard cast. @header{wx/defs.h} @@ -536,8 +729,8 @@ public: #define wx_const_cast(T, x) /** - Same as reinterpret_cast(x) if the compiler supports reinterpret cast or - (T)x for old compilers. + Same as @c reinterpret_cast(x) if the compiler supports reinterpret cast or + @c (T)x for old compilers. @header{wx/defs.h} @@ -546,10 +739,10 @@ public: #define wx_reinterpret_cast(T, x) /** - Same as static_cast(x) if the compiler supports static cast or (T)x for + Same as @c static_cast(x) if the compiler supports static cast or @c (T)x for old compilers. Unlike wxStaticCast(), there are no checks being done and the meaning of the macro arguments is exactly the same as for the standard - static cast, i.e. T is the full type name and star is not appended to it. + static cast, i.e. @a T is the full type name and star is not appended to it. @header{wx/defs.h} @@ -567,7 +760,7 @@ public: #define wx_truncate_cast(T, x) /** - This macro expands into const_cast(ptr) if the compiler + This macro expands into const_cast(ptr) if the compiler supports const_cast or into an old, C-style cast, otherwise. @header{wx/defs.h} @@ -576,20 +769,6 @@ public: */ #define wxConstCast( ptr, classname ) -/** - This is defined in debug mode to be call the redefined new operator - with filename and line number arguments. The definition is: - - @code - #define WXDEBUG_NEW new(__FILE__,__LINE__) - @endcode - - In non-debug mode, this is defined as the normal new operator. - - @header{wx/object.h} -*/ -#define WXDEBUG_NEW( arg ) - /** This macro returns the pointer @e ptr cast to the type @e classname * if the pointer is of this type (the check is done during the run-time) or @@ -615,13 +794,12 @@ public: } @endcode - @see @ref overview_runtimeclassoverview "RTTI Overview", - wxDynamicCastThis(), wxConstCast(), wxStaticCast() + @see @ref overview_rtti, wxDynamicCastThis(), wxConstCast(), wxStaticCast() */ #define wxDynamicCast( ptr, classname ) /** - This macro is equivalent to wxDynamicCast() but the latter provokes + This macro is equivalent to wxDynamicCast(this, classname) but the latter provokes spurious compilation warnings from some compilers (because it tests whether @c this pointer is non-@NULL which is always true), so this macro should be used to avoid them. @@ -635,7 +813,7 @@ public: /** This macro checks that the cast is valid in debug mode (an assert failure will result if wxDynamicCast(ptr, classname) == @NULL) and then returns the - result of executing an equivalent of static_cast(ptr). + result of executing an equivalent of static_cast(ptr). @header{wx/object.h} @@ -654,3 +832,22 @@ wxObject *wxCreateDynamicObject(const wxString& className); //@} +/** @ingroup group_funcmacro_debug */ +//@{ + +/** + This is defined in debug mode to be call the redefined new operator + with filename and line number arguments. The definition is: + + @code + #define WXDEBUG_NEW new(__FILE__,__LINE__) + @endcode + + In non-debug mode, this is defined as the normal new operator. + + @header{wx/object.h} +*/ +#define WXDEBUG_NEW( arg ) + +//@} +