X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1729acd85bacc7b911e41d35c6094bba82fc9b30..7e04f44c8df9a8571d5304718de9a5617701dbab:/interface/wx/object.h?ds=sidebyside diff --git a/interface/wx/object.h b/interface/wx/object.h index 72efca8132..787e5f7a13 100644 --- a/interface/wx/object.h +++ b/interface/wx/object.h @@ -1,18 +1,22 @@ ///////////////////////////////////////////////////////////////////////////// // Name: object.h -// Purpose: interface of wxObjectRefData +// Purpose: interface of wxRefCounter // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// -/** - @class wxObjectRefData +/** @class wxObjectRefData + + This class is just a typedef to wxRefCounter and is used by wxObject. - This class is used to store reference-counted data. + Derive classes from this to store your own data in wxObject-derived + classes. When retrieving information from a wxObject's reference data, + you will need to cast to your own derived class. - 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. + Below is an example illustrating how to store reference counted + data in a class derived from wxObject including copy-on-write + semantics. @section objectrefdata_example Example @@ -87,7 +91,7 @@ m_refData = new MyCarRefData(); M_CARDATA->m_price = price; } - + wxObjectRefData *MyCar::CreateRefData() const { return new MyCarRefData; @@ -102,7 +106,7 @@ { if (m_refData == car.m_refData) return true; - if (!m_refData || !car.m_refData) + if (!m_refData || !car.m_refData) return false; // here we use the MyCarRefData::operator==() function. @@ -137,26 +141,45 @@ @see wxObject, wxObjectDataPtr, @ref overview_refcount */ -class wxObjectRefData +typedef wxRefCounter wxObjectRefData; + + +/** + @class wxRefCounter + + This class is used to manage reference-counting providing a simple + interface and a counter. wxRefCounter can be easily used together + with wxObjectDataPtr to ensure that no calls to wxRefCounter::DecRef() + are missed - thus avoiding memory leaks. + + wxObjectRefData is a typedef to wxRefCounter and is used as the + built-in reference counted storage for wxObject-derived classes. + + @library{wxbase} + @category{rtti} + + @see wxObject, wxObjectRefData, wxObjectDataPtr, @ref overview_refcount +*/ +class wxRefCounter { protected: /** Destructor. - It's declared @c protected so that wxObjectRefData instances + It's declared @c protected so that wxRefCounter instances will never be destroyed directly but only as result of a DecRef() call. */ - virtual ~wxObjectRefData(); + virtual ~wxRefCounter(); public: /** Default constructor. Initialises the internal reference count to 1. */ - wxObjectRefData(); + wxRefCounter(); /** Decrements the reference count associated with this shared data and, if - it reaches zero, destroys this instance of wxObjectRefData releasing its + it reaches zero, destroys this instance of wxRefCounter releasing its memory. Please note that after calling this function, the caller should @@ -198,14 +221,14 @@ public: 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 + See wxRefCounter and @ref overview_refcount for more info about reference counting. @library{wxbase} @category{rtti} - @see wxClassInfo, @ref overview_debugging, @ref overview_refcount, - wxObjectRefData, wxObjectDataPtr + @see wxClassInfo, @ref overview_debugging, @ref overview_refcount, + wxObjectDataRef, wxObjectDataPtr */ class wxObject { @@ -334,10 +357,10 @@ 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), + 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. @@ -347,7 +370,7 @@ protected: /** 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 @@ -361,7 +384,7 @@ protected: /** 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 @@ -459,8 +482,8 @@ public: /** - This is an helper template class primarily written to avoid memory leaks because of - missing calls to wxObjectRefData::DecRef(). + This is an helper template class primarily written to avoid memory leaks because + of missing calls to wxRefCounter::DecRef() and 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 @@ -470,28 +493,22 @@ public: counting to be in the class pointed to, where instead wxSharedPtr implements the reference counting itself. + Below is an example illustrating how to implement reference counted + data using wxRefCounter and wxObjectDataPtr with copy-on-write + semantics. + @section objectdataptr_example Example @code - class MyCarRefData: public wxObjectRefData + class MyCarRefData: public wxRefCounter { public: - MyCarRefData() { m_price = 0; } - - MyCarRefData( const MyCarRefData& data ) - : wxObjectRefData() - { - m_price = data.m_price; - } + MyCarRefData( int price = 0 ) : m_price(price) { } + MyCarRefData( const MyCarRefData& data ) : m_price(data.m_price) { } void SetPrice( int price ) { m_price = price; } int GetPrice() const { return m_price; } - bool operator == ( const MyCarRefData& other ) const - { - return m_price == other.m_price; - } - protected: int m_price; }; @@ -501,9 +518,8 @@ public: public: // initializes this MyCar assigning to the // internal data pointer a new instance of MyCarRefData - MyCar( int price ) : m_data( new MyCarRefData ) + MyCar( int price = 0 ) : m_data( new MyCarRefData(price) ) { - m_data->SetPrice( price ); } MyCar& operator =( const MyCar& tocopy ) @@ -520,9 +536,8 @@ public: 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()); + + return (m_data.GetPrice() == other.m_data.GetPrice()); } void SetPrice( int price ) @@ -530,7 +545,7 @@ public: // make sure changes to this class do not affect other instances // currently sharing our same refcounted data: UnShare(); - + m_data->SetPrice( price ); }