/**
@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 wxObject's reference data, you will need to cast to your own derived class.
- @b Example:
+ @section objectrefdata_example Example
@code
// include file
+ // ------------
- class MyCar: public wxObject
+ class MyCar : public wxObject
{
public:
MyCar() { }
// implementation
+ // --------------
- class MyCarRefData: public wxObjectRefData
+ // the reference data class is typically a private class only visible in the
+ // implementation source file of the refcounted class.
+ class MyCarRefData : public wxObjectRefData
{
public:
MyCarRefData()
MyCarRefData( const MyCarRefData& data )
: wxObjectRefData()
{
+ // copy refcounted data; this is usually a time- and memory-consuming operation
+ // and is only done when two (or more) MyCar instances need to unshare a
+ // common instance of MyCarRefData
m_price = data.m_price;
}
return m_price == data.m_price;
}
+ private:
+ // in real world, reference counting is usually used only when
+ // the wxObjectRefData-derived class holds data very memory-consuming;
+ // in this example the various MyCar instances may share a MyCarRefData
+ // instance which however only takes 4 bytes for this integer!
int m_price;
};
#define M_CARDATA ((MyCarRefData *)m_refData)
-
IMPLEMENT_DYNAMIC_CLASS(MyCar,wxObject)
MyCar::MyCar( int price )
{
+ // here we init the MyCar internal data:
m_refData = new MyCarRefData();
M_CARDATA->m_price = price;
}
-
+
wxObjectRefData *MyCar::CreateRefData() const
{
return new MyCarRefData;
bool MyCar::operator == ( const MyCar& car ) const
{
- if (m_refData == car.m_refData) return true;
-
- if (!m_refData || !car.m_refData) return false;
-
+ if (m_refData == car.m_refData)
+ return true;
+ if (!m_refData || !car.m_refData)
+ return false;
+
+ // here we use the MyCarRefData::operator==() function.
+ // Note however that this comparison may be very slow if the
+ // reference data contains a lot of data to be compared.
return ( *(MyCarRefData*)m_refData == *(MyCarRefData*)car.m_refData );
}
void MyCar::SetPrice( int price )
{
+ // since this function modifies one of the MyCar internal property,
+ // we need to be sure that the other MyCar instances which share the
+ // same MyCarRefData instance are not affected by this call.
+ // I.e. it's very important to call UnShare() in all setters of
+ // refcounted classes!
UnShare();
M_CARDATA->m_price = price;
{
wxCHECK_MSG( IsOk(), -1, "invalid car" );
- return (M_CARDATA->m_price);
+ return M_CARDATA->m_price;
}
@endcode
It's declared @c protected so that wxObjectRefData instances
will never be destroyed directly but only as result of a DecRef() call.
*/
- ~wxObjectRefData();
+ virtual ~wxObjectRefData();
public:
/**
/**
@class wxObject
- @wxheader{object.h}
This is the root class of many of the wxWidgets classes.
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").
+ See wxObjectRefData and @ref overview_refcount for more info about
+ reference counting.
@library{wxbase}
@category{rtti}
- @see wxClassInfo, @ref overview_debugging, wxObjectRefData
+ @see wxClassInfo, @ref overview_debugging, @ref overview_refcount,
+ wxObjectRefData, wxObjectDataPtr<T>
*/
class wxObject
{
public:
+ /**
+ Default ctor; initializes to @NULL the internal reference data.
+ */
wxObject();
/**
Copy ctor.
+
+ Sets the internal wxObject::m_refData pointer to point to the same
+ instance of the wxObjectRefData-derived class pointed by @c other and
+ increments the refcount of wxObject::m_refData.
*/
wxObject(const wxObject& other);
-
/**
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 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.
- The implementation of this function in wxObject just writes
- the class name of the object.
- */
- void Dump(ostream& stream);
+ virtual ~wxObject();
/**
This virtual function is redefined for every class that requires run-time
type information, when using the ::DECLARE_CLASS macro (or similar).
*/
- wxClassInfo* GetClassInfo();
+ virtual wxClassInfo* GetClassInfo() const;
/**
Returns the wxObject::m_refData pointer, i.e. the data referenced by this object.
@return @true if the class represented by info is the same class as this
one or is derived from it.
*/
- bool IsKindOf(wxClassInfo* info);
+ bool IsKindOf(const wxClassInfo* info) const;
/**
Returns @true if this object has the same data pointer as @a obj.
@see @ref overview_refcount
*/
- bool IsSameAs(const wxObject& obj);
+ bool IsSameAs(const wxObject& obj) const;
/**
Makes this object refer to the data in @a clone.
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.
+ This is the same of AllocExclusive() but this method is public.
*/
void UnShare();
void* operator new(size_t size, const wxString& filename = NULL, int lineNum = 0);
protected:
+ /**
+ Ensure that this object's data is not shared with any other object.
+
+ If we have no data, it is created using CreateRefData();
+ if we have shared data (i.e. data with a reference count greater than 1),
+ it is copied using CloneRefData(); otherwise nothing is done (the data
+ is already present and is not shared by other object instances).
+
+ If you use this function you should make sure that you override the
+ CreateRefData() and CloneRefData() functions in your class otherwise
+ an assertion will fail at runtime.
+ */
+ void AllocExclusive();
+
+ /**
+ Creates a new instance of the wxObjectRefData-derived class specific to
+ this object and returns it.
+
+ This is usually implemented as a one-line call:
+ @code
+ wxObjectRefData *MyObject::CreateRefData() const
+ {
+ return new MyObjectRefData;
+ }
+ @endcode
+ */
+ virtual wxObjectRefData *CreateRefData() const;
+
+ /**
+ Creates a new instance of the wxObjectRefData-derived class specific to
+ this object and initializes it copying @a data.
+
+ This is usually implemented as a one-line call:
+ @code
+ wxObjectRefData *MyObject::CloneRefData(const wxObjectRefData *data) const
+ {
+ // rely on the MyObjectRefData copy ctor:
+ return new MyObjectRefData(*(MyObjectRefData *)data);
+ }
+ @endcode
+ */
+ virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const;
/**
Pointer to an object which is the object's reference-counted data.
@see Ref(), UnRef(), SetRefData(), GetRefData(), wxObjectRefData
*/
- wxObjectRefData* m_refData;
+ wxObjectRefData* m_refData;
};
/**
@class wxClassInfo
- @wxheader{object.h}
This class stores meta-information about classes.
/**
Finds the wxClassInfo object for a class with the given @a name.
*/
- static wxClassInfo* FindClass(wxChar* name);
+ static wxClassInfo* FindClass(const wxString& className);
/**
Returns the name of the first base class (@NULL if none).
*/
- wxChar* GetBaseClassName1() const;
+ const wxChar* GetBaseClassName1() const;
/**
Returns the name of the second base class (@NULL if none).
*/
- wxChar* GetBaseClassName2() const;
+ const wxChar* GetBaseClassName2() const;
/**
Returns the string form of the class name.
*/
- wxChar* GetClassName() const;
+ const wxChar* GetClassName() const;
/**
Returns the size of the class.
*/
int GetSize() const;
- /**
- Initializes pointers in the wxClassInfo objects for fast execution of IsKindOf().
- Called in base wxWidgets library initialization.
- */
- static void InitializeClasses();
-
/**
Returns @true if this class info can create objects of the associated class.
*/
/**
Returns @true if this class is a kind of (inherits from) the given class.
*/
- bool IsKindOf(wxClassInfo* info);
+ bool IsKindOf(const wxClassInfo* info) const;
};
/**
- @wxheader{object.h}
- This is helper template class primarily written to avoid memory leaks because of
+ This is an 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
methods @b T::IncRef() and @b T::DecRef().
The difference to wxSharedPtr<T> is that wxObjectDataPtr<T> relies on the reference
- counting to be in the class pointed to where instead wxSharedPtr<T> implements the
+ counting to be in the class pointed to, where instead wxSharedPtr<T> implements the
reference counting itself.
-
- @b Example:
+ @section objectdataptr_example Example
@code
class MyCarRefData: public wxObjectRefData
}
void SetPrice( int price ) { m_price = price; }
- int GetPrice() { return m_price; }
+ int GetPrice() const { return m_price; }
+ bool operator == ( const MyCarRefData& other ) const
+ {
+ return m_price == other.m_price;
+ }
+
protected:
int m_price;
};
class MyCar
{
public:
+ // initializes this MyCar assigning to the
+ // internal data pointer a new instance of MyCarRefData
MyCar( int price ) : m_data( new MyCarRefData )
{
m_data->SetPrice( price );
MyCar& operator =( const MyCar& tocopy )
{
+ // shallow copy: this is just a fast copy of pointers; the real
+ // memory-consuming data which typically is stored inside
+ // MyCarRefData is not copied here!
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());
+ if (m_data.get() == other.m_data.get())
+ return true; // this instance and the 'other' one share the
+ // same MyCarRefData data...
+
+ // rely on the MyCarRefData::operator==()
+ return (*m_data.get()) == (*other.m_data.get());
}
void SetPrice( int price )
{
- UnShare();
- m_data->SetPrice( price );
+ // make sure changes to this class do not affect other instances
+ // currently sharing our same refcounted data:
+ UnShare();
+
+ m_data->SetPrice( price );
}
int GetPrice() const
@see wxObject, wxObjectRefData, @ref overview_refcount, wxSharedPtr<T>,
wxScopedPtr<T>, wxWeakRef<T>
*/
+template <class T>
class wxObjectDataPtr<T>
{
public:
// Global functions/macros
// ============================================================================
-/** @ingroup group_funcmacro_rtti */
+/** @addtogroup group_funcmacro_rtti */
//@{
/**
//@}
-/** @ingroup group_funcmacro_debug */
+/** @addtogroup group_funcmacro_debug */
//@{
/**
projects / wxWidgets.git / blobdiff