X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/0e497a9db63c011d6a444f61291b670c382cd69b..1b7751aaa9a86d76a850b9267bc0c201e3cea30f:/interface/wx/object.h diff --git a/interface/wx/object.h b/interface/wx/object.h index 43beb09c31..90d6655767 100644 --- a/interface/wx/object.h +++ b/interface/wx/object.h @@ -3,15 +3,20 @@ // Purpose: interface of wxRefCounter // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @class wxObjectRefData This class is just a typedef to wxRefCounter and is used by wxObject. - 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. + 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. + + 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 @@ -37,7 +42,7 @@ virtual wxObjectRefData *CreateRefData() const; virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const; - DECLARE_DYNAMIC_CLASS(MyCar) + wxDECLARE_DYNAMIC_CLASS(MyCar) }; @@ -78,7 +83,7 @@ #define M_CARDATA ((MyCarRefData *)m_refData) - IMPLEMENT_DYNAMIC_CLASS(MyCar,wxObject) + wxIMPLEMENT_DYNAMIC_CLASS(MyCar, wxObject); MyCar::MyCar( int price ) { @@ -86,7 +91,7 @@ m_refData = new MyCarRefData(); M_CARDATA->m_price = price; } - + wxObjectRefData *MyCar::CreateRefData() const { return new MyCarRefData; @@ -101,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. @@ -130,7 +135,7 @@ } @endcode - + @library{wxbase} @category{rtti} @@ -142,7 +147,13 @@ typedef wxRefCounter wxObjectRefData; /** @class wxRefCounter - This class is used to manage reference-counting. + 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} @@ -216,7 +227,7 @@ public: @library{wxbase} @category{rtti} - @see wxClassInfo, @ref overview_debugging, @ref overview_refcount, + @see wxClassInfo, @ref overview_debugging, @ref overview_refcount, wxObjectDataRef, wxObjectDataPtr */ class wxObject @@ -246,12 +257,12 @@ public: /** This virtual function is redefined for every class that requires run-time - type information, when using the ::DECLARE_CLASS macro (or similar). + type information, when using the ::wxDECLARE_CLASS macro (or similar). */ virtual wxClassInfo* GetClassInfo() const; /** - Returns the wxObject::m_refData pointer, i.e. the data referenced by this object. + Returns the wxObject::m_refData pointer, i.e.\ the data referenced by this object. @see Ref(), UnRef(), wxObject::m_refData, SetRefData(), wxObjectRefData */ @@ -264,12 +275,12 @@ public: Example: @code - bool tmp = obj->IsKindOf(CLASSINFO(wxFrame)); + bool tmp = obj->IsKindOf(wxCLASSINFO(wxFrame)); @endcode @param info A pointer to a class information object, which may be obtained - by using the ::CLASSINFO macro. + by using the ::wxCLASSINFO macro. @return @true if the class represented by info is the same class as this one or is derived from it. @@ -346,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. @@ -359,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 @@ -373,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 @@ -401,8 +412,8 @@ protected: 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. + but indirectly through use of macros such as ::wxDECLARE_DYNAMIC_CLASS and + ::wxIMPLEMENT_DYNAMIC_CLASS. @library{wxbase} @category{rtti} @@ -471,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 @@ -482,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; }; @@ -513,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 ) @@ -532,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 ) @@ -542,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 ); } @@ -652,21 +655,12 @@ public: @header{wx/object.h} */ -#define CLASSINFO( className ) - -/** - Used inside a class declaration to declare that the class should be made - known to the class hierarchy, but objects of this class cannot be created - dynamically. The same as DECLARE_ABSTRACT_CLASS(). - - @header{wx/object.h} -*/ -#define DECLARE_CLASS( className ) +#define wxCLASSINFO( className ) /** Used inside a class declaration to declare that the class should be made known to the class hierarchy, but objects of this class cannot be created - dynamically. The same as DECLARE_CLASS(). + dynamically. @header{wx/object.h} @@ -675,7 +669,7 @@ public: @code class wxCommand: public wxObject { - DECLARE_ABSTRACT_CLASS(wxCommand) + wxDECLARE_ABSTRACT_CLASS(wxCommand); private: ... @@ -684,14 +678,14 @@ public: }; @endcode */ -#define DECLARE_ABSTRACT_CLASS( className ) +#define wxDECLARE_ABSTRACT_CLASS( className ) /** Used inside a class declaration to make the class known to wxWidgets RTTI system and also declare that the objects of this class should be dynamically creatable from run-time type information. Notice that this implies that the class should have a default constructor, if this is not - the case consider using DECLARE_CLASS(). + the case consider using wxDECLARE_ABSTRACT_CLASS(). @header{wx/object.h} @@ -700,7 +694,7 @@ public: @code class wxFrame: public wxWindow { - DECLARE_DYNAMIC_CLASS(wxFrame) + wxDECLARE_DYNAMIC_CLASS(wxFrame); private: const wxString& frameTitle; @@ -709,35 +703,29 @@ public: }; @endcode */ -#define DECLARE_DYNAMIC_CLASS( className ) +#define wxDECLARE_DYNAMIC_CLASS( className ) /** - Used in a C++ implementation file to complete the declaration of a class - that has run-time type information. The same as IMPLEMENT_ABSTRACT_CLASS(). - - @header{wx/object.h} -*/ -#define IMPLEMENT_CLASS( className, baseClassName ) + Used inside a class declaration to declare that the class should be made + known to the class hierarchy, but objects of this class cannot be created + dynamically. -/** - Used in a C++ implementation file to complete the declaration of a class - that has run-time type information and two base classes. The same as - IMPLEMENT_ABSTRACT_CLASS2(). + The same as wxDECLARE_ABSTRACT_CLASS(). @header{wx/object.h} */ -#define IMPLEMENT_CLASS2( className, baseClassName1, baseClassName2 ) +#define wxDECLARE_CLASS( className ) /** Used in a C++ implementation file to complete the declaration of a class - that has run-time type information. The same as IMPLEMENT_CLASS(). - + that has run-time type information. + @header{wx/object.h} Example: @code - IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject) + wxIMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject); wxCommand::wxCommand(void) { @@ -745,16 +733,15 @@ public: } @endcode */ -#define IMPLEMENT_ABSTRACT_CLASS( className, baseClassName ) +#define wxIMPLEMENT_ABSTRACT_CLASS( className, baseClassName ) /** Used in a C++ implementation file to complete the declaration of a class - that has run-time type information and two base classes. The same as - IMPLEMENT_CLASS2(). + that has run-time type information and two base classes. @header{wx/object.h} */ -#define IMPLEMENT_ABSTRACT_CLASS2( className, baseClassName1, baseClassName2 ) +#define wxIMPLEMENT_ABSTRACT_CLASS2( className, baseClassName1, baseClassName2 ) /** Used in a C++ implementation file to complete the declaration of a class @@ -766,7 +753,7 @@ public: Example: @code - IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow) + wxIMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow); wxFrame::wxFrame(void) { @@ -774,7 +761,7 @@ public: } @endcode */ -#define IMPLEMENT_DYNAMIC_CLASS( className, baseClassName ) +#define wxIMPLEMENT_DYNAMIC_CLASS( className, baseClassName ) /** Used in a C++ implementation file to complete the declaration of a class @@ -783,7 +770,25 @@ public: @header{wx/object.h} */ -#define IMPLEMENT_DYNAMIC_CLASS2( className, baseClassName1, baseClassName2 ) +#define wxIMPLEMENT_DYNAMIC_CLASS2( className, baseClassName1, baseClassName2 ) + +/** + Used in a C++ implementation file to complete the declaration of a class + that has run-time type information, and whose instances can be created + dynamically. The same as wxIMPLEMENT_DYNAMIC_CLASS(). + + @header{wx/object.h} +*/ +#define wxIMPLEMENT_CLASS( className, baseClassName ) + +/** + Used in a C++ implementation file to complete the declaration of a class + that has run-time type information and two base classes, and whose instances + can be created dynamically. The same as wxIMPLEMENT_DYNAMIC_CLASS2(). + + @header{wx/object.h} +*/ +#define wxIMPLEMENT_CLASS2( className, baseClassName1, baseClassName2 ) /** Same as @c const_cast(x) if the compiler supports const cast or @c (T)x for